This guide walks through a complete RecordEngine installation on a fresh Ubuntu server. By the end you’ll have a running instance accessible from your browser over HTTPS.
Before starting, confirm your server meets the System Requirements — particularly the NVIDIA GPU requirement. RecordEngine will not run without a supported GPU.
Overview
Installation has five stages:
- Prepare the server (GPU drivers, Docker, NVIDIA Container Toolkit)
- Install RecordEngine
- Configure your environment
- Start the containers and pull the AI model
- Set up HTTPS and log in
Total time: 45–90 minutes (most of which is waiting for downloads).
Stage 1 — Prepare the Server
Verify GPU Drivers
You should see your GPU model and driver version. If this command fails, install the NVIDIA drivers first:
sudo apt update
sudo ubuntu-drivers autoinstall
sudo reboot
nvidia-smi again to confirm.
Install Docker
curl -fsSL https://get.docker.com | bash
sudo usermod -aG docker $USER
newgrp docker
# Verify
docker --version
docker compose version
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 update && sudo apt 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
Stage 2 — Install RecordEngine
# Install git and nginx
sudo apt install -y git nginx certbot python3-certbot-nginx
# Create the application directory
sudo mkdir -p /opt/xr
sudo chown $USER:$USER /opt/xr
cd /opt/xr
# Clone the repository
git clone https://github.com/YOUR_ORG/xr-platform.git .
# Create required data directories
mkdir -p data storage ollama-data
# Install the xr management command
sudo cp xr /usr/local/bin/xr
sudo chmod +x /usr/local/bin/xr
Open the Docker Compose configuration file:
nano /opt/xr/cloud/docker-compose.yml
SERVER_URL environment variable in both the ui and api service sections. This must be your server’s public URL — the one users will access in their browser:
environment:
SERVER_URL: https://YOUR-DOMAIN.recordengine.ai
YAML indentation is significant. Every environment variable must be indented exactly 2 spaces under the environment: key. A single extra space will silently prevent the variable from loading.
Stage 4 — Start the Containers
cd /opt/xr/cloud
docker compose up -d
xr-ui, xr-watcher, xr-api, and ollama all showing as Up.
Pull the AI Model
The AI model needs to be downloaded once into the Ollama container. This is a ~6.6 GB download:
docker exec ollama ollama pull qwen3.5:9b
docker exec ollama ollama run qwen3.5:9b "Ready" --keepalive -1
Ctrl+D to exit the interactive session.
This warmup step is important. The first real document a user processes will otherwise trigger the model load, causing an apparent delay of several minutes. Running the warmup now means the first user experience is fast.
Stage 5 — Set Up HTTPS
Create the Nginx site configuration:
sudo nano /etc/nginx/sites-available/recordengine
YOUR-DOMAIN.recordengine.ai with your actual domain:
server {
listen 80;
server_name YOUR-DOMAIN.recordengine.ai;
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_set_header X-Real-IP $remote_addr;
proxy_read_timeout 120;
}
}
sudo ln -s /etc/nginx/sites-available/recordengine /etc/nginx/sites-enabled/
sudo nginx -t && sudo systemctl reload nginx
Enable SSL
sudo certbot --nginx -d YOUR-DOMAIN.recordengine.ai
Point Your Domain
In your DNS provider, create an A record pointing your subdomain to your server’s public IP address:
Type: A
Name: YOUR-SUBDOMAIN
Value: YOUR-SERVER-IP
TTL: 300
First Login
Open https://YOUR-DOMAIN.recordengine.ai in your browser. The First-Time Setup Wizard appears:
Create your admin account
Set your admin username and password. This is the master account — store the credentials safely.
Name your instance
Enter a display name for this RecordEngine instance (e.g. “Acme Finance — Shanghai”).
Choose a theme
Select your preferred colour theme. This can be changed at any time in Settings.
Verify Installation
Run the test suite to confirm everything is working correctly:
All 80 tests should pass. If any fail, check docker logs xr-ui --tail 100 for error details.
Next Steps
