# 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**

   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](/deploy-syntho/deploy-syntho-using-docker/prerequisites.md) 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](/deploy-syntho/deploy-syntho-using-docker/troubleshooting.md).
{% endstep %}

{% step %}
**Back up PostgreSQL**

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

### Next steps

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


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.syntho.ai/deploy-syntho/deploy-syntho-using-docker.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.