Docker Compose

Run the full Syntho stack on a single machine using Docker Compose.

What Docker Compose deploys

The Compose bundle runs the full stack on one host:

• Frontend (UI)

• Backend

• Core API

• Ray

• PostgreSQL (metadata)

• Redis

Some bundles let you point to external PostgreSQL/Redis instead.

Offline deployment

Offline deployments require the steps below. You need to stage artifacts on a connected machine first.

1. Stage the compose bundle

   You cannot fetch templates from GitHub on the offline host.

   1. Download or clone the deployment-tools repo.

   2. Copy the docker-compose/ folder (including postgres/) to the offline host.

2. Stage container images

   The offline host cannot pull images from the Syntho registry. There are two alternatives:

   • Recommended: mirror images into an internal registry reachable by the offline host. Then update image references in docker-compose.yaml to the internal registry hostname.

   • Alternative: docker save / docker load images as tarballs.

   Practical flow for tarballs:

   1. Log in to the Syntho registry.

   2. Pull the images for the APPLICATION_VERSION you will deploy.

   3. Export them:

docker save -o syntho-images.tar \
  <image-1>:<tag> <image-2>:<tag> <image-n>:<tag>

1. Transfer syntho-images.tar to the offline host.

2. Import them on the offline host:

docker load -i syntho-images.tar

1. Registry authentication step changes

   • If you load images locally, skip registry login on the offline host.

   • If you use an internal registry, log in to that registry instead.

Upgrades are the same procedure. Repeat the staging step for the new APPLICATION_VERSION.

Deploy

1

Prerequisites

Make sure you meet the prerequisites before deploying.

2

Get the Docker Compose templates

Use the templates from the deployment-tools repository:

• Docker Compose templates

Key files in that folder:

• .env (template)

• docker-compose.yaml

Keep .env and docker-compose.yaml in the same directory.

Also keep the postgres/ folder next to them. It contains the init script that creates the required databases.

3

Authenticate to the container registry

Use the registry host and credentials provided by Syntho to login with:

docker login syntho.azurecr.io -u <USERNAME> -p <PASSWORD>

Ensure that syntho.azurecr.io is added to your firewall allowlist to enable image pulls

4

Configure .env

Edit .env in the same directory as docker-compose.yaml.

Set at least:

• APPLICATION_VERSION: Syntho version to deploy.

• LICENSE_KEY: your Syntho license key.

• SECRET_KEY: secret used by Syntho security mechanisms.

• USER_EMAIL: email for the initial admin user.

• USER_PASSWORD: password for the initial admin user.

• DB_PASSWORD: password for the bundled PostgreSQL (required by docker-compose.yaml).

The default Compose bundle assumes DB_USER=syntho. Set DB_PASSWORD yourself.

Generate a SECRET_KEY (if needed, Syntho will provide one as well):

python -c "from cryptography.fernet import Fernet; print(Fernet.generate_key().decode())"

Rotate secret keys carefully.

Syntho uses secret keys for sessions and encryption.

Changing keys can break sessions.

It can also make previously stored encrypted values unreadable.

Plan key rotation:

1. Back up PostgreSQL metadata databases.

2. Stop traffic and running jobs.

3. Rotate keys.

4. Restart services.

5. Verify login and basic workflows.

If you are unsure what do do, ask Syntho Support.

UI URL, ports, and HTTPS

By default UI is exposed on port 3000 and the API on 8000.

If you terminate TLS in a reverse proxy, ensure:

• The UI is configured for https.

• Secure cookies are enabled when using HTTPS.

FRONTEND_DOMAIN=<hostname-or-ip>
FRONTEND_PROTOCOL=http   # set to https when using TLS
SECURE_COOKIES=False     # set to True when using https
FRONTEND_PORT=3000
BACKEND_PORT=8000

5

Start Syntho

docker compose up -d

6

Verify deployment

Check containers status with:

docker compose ps

Open the UI:

• <FRONTEND_PROTOCOL>://<FRONTEND_DOMAIN>:<FRONTEND_PORT>

Use the admin credentials you configured in .env.

The FRONTEND_DOMAIN / FRONTEND_PORT can be found in the .env

If this does not work, see Troubleshooting.

7

Back up PostgreSQL

Back up PostgreSQL Syntho application databases before first use to validate the process.

Next steps

• Day-to-day commands: Operations

• Upgrade procedure: Upgrade

• Common issues: Troubleshooting