# Docker Compose

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

<details>

<summary>What Docker Compose deploys</summary>

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.

</details>

<details>

<summary>Offline deployment</summary>

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**&#x20;

   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:

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

4. Transfer `syntho-images.tar` to the offline host.
5. Import them on the offline host:

```bash
docker load -i syntho-images.tar
```

3. **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.

{% hint style="info" %}
Upgrades are the same procedure. Repeat the staging step for the new `APPLICATION_VERSION`.
{% endhint %}

</details>

### Deploy

{% stepper %}
{% step %}

#### Prerequisites

Make sure you meet the [prerequisites](https://docs.syntho.ai/deploy-syntho/deploy-syntho-using-docker/prerequisites) before deploying.
{% endstep %}

{% step %}

#### Get the Docker Compose templates

Use the templates from the `deployment-tools` repository:

* [Docker Compose templates](https://github.com/syntho-ai/deployment-tools/tree/main/docker-compose)

Key files in that folder:

* [`.env` (template)](https://github.com/syntho-ai/deployment-tools/blob/main/docker-compose/.env)
* [`docker-compose.yaml`](https://github.com/syntho-ai/deployment-tools/blob/main/docker-compose/docker-compose.yaml)

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

Also keep the [`postgres/`](https://github.com/syntho-ai/deployment-tools/tree/main/docker-compose/postgres) folder next to them. It contains the init script that creates the required databases.
{% endstep %}

{% step %}

#### Authenticate to the container registry

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

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

{% hint style="info" %}
Ensure that `syntho.azurecr.io` is added to your firewall allowlist to enable image pulls
{% endhint %}
{% endstep %}

{% step %}

#### 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`).

{% hint style="info" %}
The default Compose bundle assumes `DB_USER=syntho`. Set `DB_PASSWORD` yourself.
{% endhint %}

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

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

{% hint style="warning" %}
Rotate secret keys carefully.
{% endhint %}

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.

<details>

<summary>UI URL, ports, and HTTPS</summary>

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.

```bash
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
```

</details>
{% endstep %}

{% step %}

#### Start Syntho

```bash
docker compose up -d
```

{% endstep %}

{% step %}

#### Verify deployment

Check containers status with:

```bash
docker compose ps
```

Open the UI:

* `<FRONTEND_PROTOCOL>://<FRONTEND_DOMAIN>:<FRONTEND_PORT>`

Use the admin credentials you configured in `.env`.

{% hint style="info" %}
The `FRONTEND_DOMAIN` / `FRONTEND_PORT` can be found in the `.env`
{% endhint %}

If this does not work, see [Troubleshooting](https://docs.syntho.ai/deploy-syntho/deploy-syntho-using-docker/troubleshooting).
{% endstep %}

{% step %}

#### Back up PostgreSQL

[Back up PostgreSQL](https://docs.syntho.ai/deploy-syntho/deploy-syntho-using-docker/back-up-postgresql) Syntho application databases before first use to validate the process.
{% endstep %}
{% endstepper %}

### Next steps

* Day-to-day commands: [Operations](https://docs.syntho.ai/deploy-syntho/deploy-syntho-using-docker/operations)
* Upgrade procedure: [Upgrade](https://docs.syntho.ai/deploy-syntho/deploy-syntho-using-docker/upgrade)
* Common issues: [Troubleshooting](https://docs.syntho.ai/deploy-syntho/deploy-syntho-using-docker/troubleshooting)