This guide covers deploying RecordEngine on a bare Linux server. The recommended deployment uses Ubuntu 22.04 or 24.04 with an NVIDIA GPU (RTX 4090 or RTX 5090 for on-premise hardware, A10G for cloud).
Prerequisites
Before starting, ensure the following are installed and working on your server:
| Requirement | Version | Notes |
|---|
| Ubuntu | 22.04 or 24.04 | Other Debian-based distros work but are untested |
| Docker Engine | 24.0+ | Install via Docker’s official repo — not apt default |
| Docker Compose | v2.20+ | Included with modern Docker Engine |
| NVIDIA GPU Driver | 525+ | Run nvidia-smi to verify |
| NVIDIA Container Toolkit | Latest | Allows Docker to access the GPU |
| Git | Any | For pulling the codebase |
# Add NVIDIA container toolkit repo
curl -fsSL https://nvidia.github.io/libnvidia-container/gpgkey | sudo gpg --dearmor -o /usr/share/keyrings/nvidia-container-toolkit-keyring.gpg
curl -s -L https://nvidia.github.io/libnvidia-container/stable/deb/nvidia-container-toolkit.list | \
sed 's#deb https://#deb [signed-by=/usr/share/keyrings/nvidia-container-toolkit-keyring.gpg] https://#g' | \
sudo tee /etc/apt/sources.list.d/nvidia-container-toolkit.list
sudo apt-get update && sudo apt-get install -y nvidia-container-toolkit
sudo nvidia-ctk runtime configure --runtime=docker
sudo systemctl restart docker
docker run --rm --gpus all nvidia/cuda:11.8.0-base-ubuntu22.04 nvidia-smi
Installation
1 — Clone the repository
sudo mkdir -p /opt/xr
sudo chown $USER:$USER /opt/xr
cd /opt/xr
git clone https://github.com/YOUR-ORG/xr-platform.git .
2 — Create environment configuration
cp cloud/.env.example cloud/.env
nano cloud/.env
# Instance identity
INSTANCE_NAME=My Company RecordEngine
SERVER_URL=https://your-domain.com
# Security — generate a strong random string for each
SECRET_KEY=your-secret-key-here
API_TOKEN=your-api-token-here
# AI models
CHAT_MODEL=qwen3.5:9b
STRUCTURED_MODEL=qwen3.5:9b
SUMMARY_MODEL=qwen3.5:9b
VISION_MODEL=qwen3.5:9b
OLLAMA_KEEP_ALIVE=-1
Use a strong, randomly generated value for SECRET_KEY and API_TOKEN. These control access to your instance. You can generate them with openssl rand -hex 32.
3 — Start the containers
cd /opt/xr/cloud
docker compose up -d
xr-ui, xr-watcher, xr-api, and ollama.
4 — Pull the AI model
docker exec ollama ollama pull qwen3.5:9b
ollama-data volume. Run a warmup prompt so the model loads into GPU memory before the first real document arrives:
docker exec ollama ollama run qwen3.5:9b "Hello" --nowordwrap
5 — Verify containers are running
All four containers should show Up. Access the UI at http://YOUR-SERVER-IP:8501.
First-Run Setup
On first access, RecordEngine runs a setup wizard:
- Create the Admin account — set username and password for the first admin user
- Instance name — displayed in the UI header
- Done — you’re redirected to the dashboard
There is no default password. The setup wizard only runs once — on first access after a fresh installation. If you need to reset the admin account, see Troubleshooting.
RecordEngine should be served over HTTPS in production. The recommended approach uses Nginx as a reverse proxy with Let’s Encrypt for SSL.
Install Nginx and Certbot
sudo apt-get install -y nginx certbot python3-certbot-nginx
Create an Nginx site configuration
# /etc/nginx/sites-available/recordengine
server {
listen 80;
server_name your-domain.com;
location / {
proxy_pass http://localhost:8501;
proxy_http_version 1.1;
proxy_set_header Upgrade $http_upgrade;
proxy_set_header Connection "upgrade";
proxy_set_header Host $host;
proxy_read_timeout 120;
}
location /api/ {
proxy_pass http://localhost:8510/;
proxy_set_header Host $host;
proxy_read_timeout 120;
}
}
sudo ln -s /etc/nginx/sites-available/recordengine /etc/nginx/sites-enabled/
sudo nginx -t && sudo systemctl reload nginx
Issue the SSL certificate
sudo certbot --nginx -d your-domain.com
Install the xr Management Command
The xr command is a convenience wrapper for common operations:
sudo cp /opt/xr/scripts/xr /usr/local/bin/xr
sudo chmod +x /usr/local/bin/xr
| Command | What it does |
|---|
xr status | Show container status |
xr start | Start all containers |
xr stop | Stop all containers |
xr restart | Restart all containers |
xr update | Pull latest code from git and restart |
xr backup | Create a backup ZIP |
xr logs | Tail live logs from all containers |
xr test | Run the test suite (80/80 baseline) |
Verify the Deployment
# All containers running
xr status
# UI accessible
curl -s -o /dev/null -w "%{http_code}" http://localhost:8501
# API accessible
curl -s http://localhost:8510/api/health
# Run full test suite
xr test
Firewall Configuration
Open only the ports you need:
sudo ufw allow 22/tcp # SSH
sudo ufw allow 80/tcp # HTTP (redirect to HTTPS)
sudo ufw allow 443/tcp # HTTPS
sudo ufw enable
