API-Mode Deployment

Overview

API-mode is a lightweight deployment option for customers who want RecordEngine in the cloud without the cost of a GPU instance.

	GPU Mode	API Mode
AI inference	Local (Ollama on GPU)	Cloud API (customer’s key)
Monthly cost	~$730/month (g5.xlarge)	~$110/month (t3a.xlarge)
Provisioning time	~20 minutes	~5 minutes (from AMI)
Data sovereignty	Full (on-premise)	API provider’s terms
Feature parity	Full	Full

Prerequisites

AWS account with EC2 access
Cloudflare DNS access for recordengine.ai
SSH key: xr-platform-key.pem
Customer’s API key (OpenAI, Claude, Gemini, or Qwen)

Deploy a New Customer Instance

Step 1 — Launch EC2 from Golden AMI

In the AWS console:

Go to EC2 → AMIs → find recordengine-api-v3
Click Launch instance from AMI
Instance type: t3a.xlarge (4 vCPU, 16 GB RAM)
Storage: 100 GiB gp3
Key pair: xr-platform-key
Security group: allow ports 22, 80, 443 inbound
Launch

Step 2 — SSH In

ssh -i C:\Users\jeand\.ssh\xr-platform-key.pem ubuntu@<NEW_IP>

Step 3 — Pull Latest Code

sudo chown -R ubuntu:ubuntu /opt/xr
git -C /opt/xr pull

Step 4 — Start Containers

cd /opt/xr/cloud
docker compose -f docker-compose.api.yml up -d

Step 5 — DNS

In Cloudflare, create an A record:

Name: clientname
Target: new instance IP
Proxy: DNS only (grey cloud — NOT orange)

Step 6 — SSL

sudo certbot --nginx -d clientname.recordengine.ai \
  --email admin@recordengine.ai \
  --agree-tos --non-interactive --redirect

Step 7 — Customer Setup

Share the URL with the customer. On first login they will:

Create their admin account
Go to Settings → AI Backend → select provider → enter API key → Save
Go to Settings → General → 🔗 Server URL → enter their URL → Save

Managing the Instance

All management uses the xr CLI. The CLI automatically detects API mode via /opt/xr/.deploy_mode.

xr status          # container status, mode, disk, DB
xr doctor          # health check
xr update          # git pull + restart + self-update CLI
xr restart-watcher # restart background worker
xr backup          # SQLite backup
xr test            # run 80-test suite
xr logs [name]     # tail container logs

xr update on the API instance will never start the Ollama container — it reads .deploy_mode and uses docker-compose.api.yml automatically.

Seed Scripts

After the first xr update, run the seed scripts to populate extraction profiles and default rules:

docker exec xr-ui python /app/seed_profiles.py
docker exec xr-ui python /app/seed_accounting_profiles.py
docker exec xr-ui python /app/seed_healthcare_profiles.py
docker exec xr-ui python /app/seed_default_rules.py

These are idempotent — safe to re-run at any time.

Architecture

The API-mode compose file (cloud/docker-compose.api.yml) runs three services:

Container	Port	Purpose
`xr-ui`	8501	Streamlit web interface
`xr-watcher`	—	Background AI processing worker
`xr-api`	8510	FastAPI REST API

The Ollama and ollama-warmup services are absent. All AI calls route through ai_router.py to the customer’s configured API provider.

Golden AMI

The recordengine-api-v3 AMI contains:

Ubuntu 24.04 LTS
Docker + Docker Compose installed
RecordEngine repo cloned at /opt/xr
Pre-built Docker images (no build step required)
Nginx configured
xr CLI installed at /usr/local/bin/xr
.deploy_mode set to api
Correct file ownership (ubuntu:ubuntu)
git safe.directory configured

Update the AMI after major releases by spinning up the current API instance, running xr update, and creating a new AMI snapshot (e.g. recordengine-api-v4).

Troubleshooting

Browser hangs on skeleton screen The config.toml is missing required settings. Verify:

cat /opt/xr/app/.streamlit/config.toml

It must contain:

[server]
headless = true
enableCORS = false
enableXsrfProtection = false

xr update tries to start Ollama The .deploy_mode file is missing or incorrect:

cat /opt/xr/.deploy_mode   # should print: api
echo "api" | sudo tee /opt/xr/.deploy_mode

Git pull fails with permission error

sudo chown -R ubuntu:ubuntu /opt/xr
git config --global --add safe.directory /opt/xr

Getting Started

User Guide

Deployment

Troubleshooting

FAQ

Overview

Prerequisites

Deploy a New Customer Instance

Step 1 — Launch EC2 from Golden AMI

Step 2 — SSH In

Step 3 — Pull Latest Code

Step 4 — Start Containers

Step 5 — DNS

Step 6 — SSL

Step 7 — Customer Setup

Managing the Instance

Seed Scripts

Architecture

Golden AMI

Troubleshooting

​Overview

​Prerequisites

​Deploy a New Customer Instance

​Step 1 — Launch EC2 from Golden AMI

​Step 2 — SSH In

​Step 3 — Pull Latest Code

​Step 4 — Start Containers

​Step 5 — DNS

​Step 6 — SSL

​Step 7 — Customer Setup

​Managing the Instance

​Seed Scripts

​Architecture

​Golden AMI

​Troubleshooting

Overview

Prerequisites

Deploy a New Customer Instance

Step 1 — Launch EC2 from Golden AMI

Step 2 — SSH In

Step 3 — Pull Latest Code

Step 4 — Start Containers

Step 5 — DNS

Step 6 — SSL

Step 7 — Customer Setup

Managing the Instance

Seed Scripts

Architecture

Golden AMI

Troubleshooting