Deploy Runtime + embedded SocketD

Start with an automatic 30-day trial, claim the Runtime in the portal, then renew the subscription without reinstalling.

Odoo 19.0 & 18.0 supported

One Docker download for all supported hosts: obtain XiotBoxRuntime-1.1.1-docker-amd64.tar.gz and its checksum from Customer Downloads. The same protected bundle runs through Docker on Windows, macOS and x86-64 Linux. Runtime already contains SocketD; do not install a second SocketD service. Executables are never included in the public Odoo Apps ZIP.

Before choosing an environment

Compiled delivery boundary

The archive contains a Nuitka-compiled Linux x86-64 Docker image, installers and configuration templates. It contains no Runtime or SocketD Python source. Configuration and tokens remain outside the executable so they can be rotated.

One service, two endpoints

Runtime HTTP and embedded SocketD run in the same hardened, non-root container. Docker is required only for this sidecar; Odoo may remain installed natively.

Common preparation

In Self-hosted Print → Configuration → Settings, generate separate Runtime and SocketD tokens and note the exact database name.
Allow Runtime to obtain its automatic 30-day trial from the License Service; purchase or renew production time later from the claimed Runtime portal page.
Download the archive only after signing in with your registered portal account.
Compare its SHA-256 value with Customer Downloads. Stop if it differs.
Back up Odoo, the Runtime data directory and any existing desktop-client configuration.

On Linux or macOS:

shasum -a 256 -c XiotBoxRuntime-1.1.1-docker-amd64.tar.gz.sha256
tar -xzf XiotBoxRuntime-1.1.1-docker-amd64.tar.gz
cd XiotBoxRuntime-1.1.1-docker-amd64
shasum -a 256 -c SHA256SUMS.txt

On Windows PowerShell, compare the displayed hash with Customer Downloads before extracting:

Get-FileHash .\XiotBoxRuntime-1.1.1-docker-amd64.tar.gz -Algorithm SHA256
tar -xzf .\XiotBoxRuntime-1.1.1-docker-amd64.tar.gz
Set-Location .\XiotBoxRuntime-1.1.1-docker-amd64

Docker Engine on Linux: the container reaches Odoo on the host through host.docker.internal. This address is automatic on Docker Desktop (Windows/macOS), but on Linux Docker Engine the Compose file must keep extra_hosts: ["host.docker.internal:host-gateway"] (the supplied template already includes it). If Runtime cannot reach Odoo, check this entry first.

Start the automatic 30-day trial

For a genuinely new Internet-connected Runtime, leave the commercial key empty. Runtime Manager generates a strong Management Token automatically; copy the same value into the Runtime deployment:

XIOTBOX_LICENSE_KEY=
XIOTBOX_LICENSE_SERVICE_URL=https://license.xiotbox.com
XIOTBOX_LICENSE_PUBLIC_KEY=the_public_verification_key_supplied_with_delivery
XIOTBOX_MANAGEMENT_TOKEN=copy_from_runtime_manager

Runtime registers its persistent installation identity on first start and receives one automatic 30-day trial. XIOTBOX_LICENSE_KEY is only for an existing paid or offline License; it is not required for the trial. The host needs outbound HTTPS access to license.xiotbox.com.

Management Token: it remains the Bearer credential used for Runtime status and License checks. Runtime Manager administrators can reveal and copy it. A mismatch returns HTTP 401. See Beginner Quick Start.

After Runtime is healthy, follow Trial, Claim and Renewal to link it to a portal account and convert the trial to a paid subscription.

For an approved offline installation, create a machine-bound request and send the generated JSON file through the offline signing process:

docker compose run --rm runtime --license-request /data/license-request.json

Place the returned signed License file in the persistent Runtime data directory and set XIOTBOX_OFFLINE_LICENSE_FILE. Never commit License keys, signed License files or private signing keys to Git.

Choose your deployment

1. Ubuntu 24.04 · package or .deb Odoo · public domainRecommended production profile

Keep the existing Odoo systemd service. Install Docker Engine and Compose v2 only for XiotBox:

sudo apt update
sudo apt install docker.io docker-compose-v2
sudo systemctl enable --now docker
cp .env.example .env
nano .env

Set the public URLs, database and both tokens:

OG_RUNTIME_PUBLIC_URL=https://print.example.com/runtime
OG_ODOO_INTERNAL_URL=http://host.docker.internal:8069
OG_ODOO_DATABASE=your_database
OG_RUNTIME_TOKEN=your_runtime_token
SOCKETD_API_BASE_URL=http://host.docker.internal:8069
SOCKETD_DB_NAME=your_database
SOCKETD_TOKEN=your_socketd_token
SOCKETD_PUBLIC_URL=tls://print.example.com:9019

Use nginx-runtime.conf.example: HTTPS /runtime forwards to loopback port 8020, while the Nginx stream module terminates SocketD TLS on public port 9019 and forwards to loopback port 19019. The certificate key stays on the host.

sudo ./install.sh
docker compose ps
curl -fsS https://print.example.com/runtime/healthz

Open only 80, 443 and 9019 in the cloud security group. Never expose Odoo 8069, Runtime 8020 or internal SocketD 19019 publicly. If Odoo listens only on 127.0.0.1, bind it to a Docker-reachable host interface and keep 8069 blocked by both the cloud and host firewalls.

2. Ubuntu 24.04 · Docker Compose Odoo · public domainShare the private Docker network

Load the offline image, then copy the supplied runtime service into the existing Odoo Compose project so both services share its private network:

docker load -i XiotBoxRuntime-image-1.1.1-linux-x86_64.tar
cp .env.example .env
nano .env

If the existing Odoo Compose service is named odoo, use its service name instead of a public address:

OG_ODOO_INTERNAL_URL=http://odoo:8069
SOCKETD_API_BASE_URL=http://odoo:8069
OG_ODOO_DATABASE=your_database
SOCKETD_DB_NAME=your_database
OG_RUNTIME_TOKEN=your_runtime_token
SOCKETD_TOKEN=your_socketd_token
OG_RUNTIME_PUBLIC_URL=https://print.example.com/runtime
SOCKETD_PUBLIC_URL=tls://print.example.com:9019

docker compose config
docker compose up -d runtime
docker compose ps
docker compose logs --tail=100 runtime

Use the existing Nginx or Traefik for Runtime HTTPS and a TCP/TLS entrypoint for SocketD. Do not publish Odoo 8069 merely to connect the two containers.

3. Windows · official Odoo EXE · no public domainTrusted LAN or acceptance test

Install Docker Desktop with WSL2 and Linux containers. Give the Windows computer a stable LAN IPv4 address or DHCP reservation. In PowerShell:

Copy-Item .env.lan.example .env
notepad .env

For a computer at 192.168.1.50:

OG_RUNTIME_PUBLIC_URL=http://192.168.1.50:8020
OG_ODOO_INTERNAL_URL=http://host.docker.internal:8069
SOCKETD_API_BASE_URL=http://host.docker.internal:8069
SOCKETD_PUBLIC_URL=tcp://192.168.1.50:9019

Fill the database and both tokens, then run:

powershell -ExecutionPolicy Bypass -File .\install.ps1
docker compose ps

Allow inbound TCP 8020 and 9019 only on the Windows Private network profile. Use the LAN address, not 127.0.0.1, because other desktop clients must reach it.

4. macOS · native Odoo · no public domainTrusted LAN or light test use

Install Docker Desktop and reserve a stable LAN address. For a Mac at 192.168.1.60:

cp .env.lan.example .env
nano .env

OG_RUNTIME_PUBLIC_URL=http://192.168.1.60:8020
OG_ODOO_INTERNAL_URL=http://host.docker.internal:8069
SOCKETD_API_BASE_URL=http://host.docker.internal:8069
SOCKETD_PUBLIC_URL=tcp://192.168.1.60:9019

Fill the database and both tokens, then:

chmod +x install.sh
./install.sh
docker compose ps

Apple Silicon runs the protected linux/amd64 image through Docker emulation. This is supported for acceptance and light LAN use, but Ubuntu x86-64 remains the recommended production Runtime host. Allow Docker network access when macOS prompts.

5. Deepin x86-64 · native Odoo · no public domainTrusted LAN or acceptance test

Install Docker Engine and Compose v2, confirm both commands work, then configure the stable LAN IP. For a Deepin host at 192.168.1.70:

docker version
docker compose version
cp .env.lan.example .env
nano .env

OG_RUNTIME_PUBLIC_URL=http://192.168.1.70:8020
OG_ODOO_INTERNAL_URL=http://host.docker.internal:8069
SOCKETD_API_BASE_URL=http://host.docker.internal:8069
SOCKETD_PUBLIC_URL=tcp://192.168.1.70:9019

Fill the database and both tokens, then:

chmod +x install.sh
./install.sh
docker compose ps

Odoo must listen on an address reachable from the Docker bridge. Restrict TCP 8020 and 9019 to the trusted LAN. The current release does not claim a native ARM64 Runtime image.

LAN profile boundary: .env.lan.example deliberately uses plaintext HTTP and TCP. Use it only on a trusted isolated LAN or acceptance environment. Any Internet exposure, untrusted Wi-Fi or site-to-site connection requires the public TLS profile.

Verify every installation

docker compose ps
docker compose logs --tail=100 runtime
curl -fsS http://YOUR_LAN_IP:8020/healthz

For a public server, use https://print.example.com/runtime/healthz instead.
Restart the service with docker compose restart runtime and repeat the health check.
Return to Odoo and confirm Runtime and SocketD are online.
Connect one patched desktop client, discover its printers and complete one harmless test print.
Confirm the container recovers after an Odoo or host restart before enabling automated printing.

Checkpoint: the compiled Runtime survives a restart, embedded SocketD is reachable, Odoo shows both services online and one real print completes exactly once.

Services are healthy.Next: claim the trial and subscribe →