Skip to main content
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:
  1. Prepare the server (GPU drivers, Docker, NVIDIA Container Toolkit)
  2. Install RecordEngine
  3. Configure your environment
  4. Start the containers and pull the AI model
  5. 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

nvidia-smi
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
After reboot, run 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

​
Install NVIDIA Container Toolkit

This allows Docker containers to access the GPU: 
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
Verify GPU access works inside Docker: 
docker run --rm --gpus all nvidia/cuda:11.8.0-base-ubuntu22.04 nvidia-smi
You should see the same GPU information as from the host. If this fails, the NVIDIA Container Toolkit is not configured correctly — do not proceed until it works.

​
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

​
Stage 3 — Configure Your Environment

Open the Docker Compose configuration file: 
nano /opt/xr/cloud/docker-compose.yml
Set the 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.
The AI model variables are pre-configured correctly — leave them as-is unless you have a specific reason to change them.

​
Stage 4 — Start the Containers

cd /opt/xr/cloud
docker compose up -d
Check that all four containers started: 
xr status
You should see 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
This takes 5–20 minutes depending on your internet connection. Once the download completes, warm up the model to load it into GPU memory: 
docker exec ollama ollama run qwen3.5:9b "Ready" --keepalive -1
The first run takes 1–3 minutes as the model loads. You’ll see a response when it’s ready. Press 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

​
Configure Nginx

Create the Nginx site configuration: 
sudo nano /etc/nginx/sites-available/recordengine
Paste the following — replacing 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;
    }
}
Enable the site and reload Nginx: 
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
Follow the prompts. Certbot configures HTTPS automatically and sets up auto-renewal.

​
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
DNS propagation takes 1–10 minutes. Once it resolves, HTTPS will be active.

​
First Login

Open https://YOUR-DOMAIN.recordengine.ai in your browser. The First-Time Setup Wizard appears:
1

Create your admin account

Set your admin username and password. This is the master account — store the credentials safely.
2

Name your instance

Enter a display name for this RecordEngine instance (e.g. “Acme Finance — Shanghai”).
3

Choose a theme

Select your preferred colour theme. This can be changed at any time in Settings.
You’re in. RecordEngine is ready to use.

​
Verify Installation

Run the test suite to confirm everything is working correctly: 
xr test
All 80 tests should pass. If any fail, check docker logs xr-ui --tail 100 for error details.

​
Next Steps

Your First Document

Upload a document and see the full extraction pipeline in action.

Extraction Profiles

Configure the fields RecordEngine extracts for each document type.

Integrations

Connect RecordEngine to QuickBooks, Xero, Salesforce, or HubSpot.

User Management

Add team members and set access roles.