# Deploy with Docker

> Run the Sypnia engine on any server with Docker Compose, next to a Postgres and an S3-compatible store, with HTTPS, a first project, its keys and a health check.

Applies to: the Sypnia engine (open source, self-hosted). Status: at launch.  
Source: https://docs.sypnia.com/self-hosting/deploy-docker/

For agents: How to deploy the self-hosted Sypnia engine on one server with Docker Compose: the full compose.yaml (engine, Postgres 16, MinIO, Caddy for HTTPS), the .env file, health check, sypnia doctor, first project, ingest key and API token with the CLI, variants with Amazon S3, Cloudflare R2, Supabase or Neon, the bucket CORS rule, day-to-day commands, removal and troubleshooting.

**\[Engine]** This page is for whoever runs the open-source engine on a server of their own, at any provider. It does not apply to Sypnia Cloud. For a trial on your laptop, without HTTPS, use the shorter [self-host quickstart](https://docs.sypnia.com/start/quickstart-self-host); for AWS without a server, [Deploy on AWS](https://docs.sypnia.com/self-hosting/deploy-aws).

**At the end you will have:** the engine at `https://sypnia.example.com` as one long-running process, a Postgres and an S3-compatible store beside it, certificates that renew themselves, a first project with an ingest key and an API token, and `sypnia doctor` passing.

**You need:** a Linux server with Docker and Compose, reachable from the internet on ports 80 and 443 (2 vCPU, 4 GB of memory and 40 GB of disk is a sensible start; see [Scaling and cost](https://docs.sypnia.com/self-hosting/scaling-and-cost)); two DNS names that point at it; `openssl`; about 30 minutes.

> **Note: Planned names**
>
> The engine is not released yet. The image `ghcr.io/sypnia/sypnia:1` is the planned one. The file below uses the same service names as the quickstart, so what you learned there still holds.

## What runs

| Service  | Image                     | What it does                                                                                | Reachable from outside                                        |
| -------- | ------------------------- | ------------------------------------------------------------------------------------------- | ------------------------------------------------------------- |
| `sypnia` | `ghcr.io/sypnia/sypnia:1` | The whole engine in one process: `sypnia serve` with the role `all`.                        | Only through `caddy`                                          |
| `db`     | `postgres:16`             | The database.                                                                               | No                                                            |
| `minio`  | `minio/minio`             | The S3-compatible store that holds the bucket.                                              | Only through `caddy`, for replay links and source-map uploads |
| `bucket` | `minio/mc`                | Creates the bucket once, then exits.                                                        | No                                                            |
| `caddy`  | `caddy:2`                 | HTTPS in front of the engine and the store, with certificates it gets and renews by itself. | Ports 80 and 443                                              |

Two DNS names are needed because browsers read replays, and your CI uploads source maps, straight from the store through short-lived signed links. With a hosted store such as Amazon S3 or Cloudflare R2 you need only one name: see [Use a hosted bucket or database](#use-a-hosted-bucket-or-database).

## Deploy

### 1. Point two names at the server

At your DNS provider, create two `A` records with the server's address:

| Name                         | For                                                    |
| ---------------------------- | ------------------------------------------------------ |
| `sypnia.example.com`         | The engine: SDKs, the API, the MCP server, the Console |
| `storage.sypnia.example.com` | The store: replay links and source-map uploads         |

```bash
dig +short sypnia.example.com storage.sypnia.example.com
```

**You should see:**The server's address, twice.

### 2. Write the secrets

In an empty folder on the server:

```bash
cat > .env <<EOF
SYPNIA_DOMAIN=sypnia.example.com
STORAGE_DOMAIN=storage.sypnia.example.com
SYPNIA_ROOT_TOKEN=$(openssl rand -hex 32)
POSTGRES_PASSWORD=$(openssl rand -hex 24)
MINIO_PASSWORD=$(openssl rand -hex 24)
EOF
chmod 600 .env
```

**You should see:**A file `.env` with five lines that only you can read. Copy the root token to your password manager: it can do everything on every project.

### 3. Write the Compose file

`compose.yaml`

```yaml
services:
  sypnia:
    image: ghcr.io/sypnia/sypnia:1
    restart: unless-stopped
    environment:
      SYPNIA_BASE_URL: https://${SYPNIA_DOMAIN}
      SYPNIA_ROOT_TOKEN: ${SYPNIA_ROOT_TOKEN}
      SYPNIA_AUTO_MIGRATE: "true"
      SYPNIA_TRUSTED_PROXY_HOPS: "1"
      SYPNIA_DATABASE_URL: postgres://sypnia:${POSTGRES_PASSWORD}@db:5432/sypnia
      SYPNIA_STORAGE_BUCKET: sypnia
      SYPNIA_STORAGE_ENDPOINT: http://minio:9000
      SYPNIA_STORAGE_PUBLIC_ENDPOINT: https://${STORAGE_DOMAIN}
      SYPNIA_STORAGE_PATH_STYLE: "true"
      SYPNIA_STORAGE_ACCESS_KEY_ID: sypnia
      SYPNIA_STORAGE_SECRET_ACCESS_KEY: ${MINIO_PASSWORD}
    depends_on:
      db: { condition: service_healthy }
      bucket: { condition: service_completed_successfully }

  db:
    image: postgres:16
    restart: unless-stopped
    environment:
      POSTGRES_USER: sypnia
      POSTGRES_PASSWORD: ${POSTGRES_PASSWORD}
      POSTGRES_DB: sypnia
    volumes: ["db:/var/lib/postgresql/data"]
    healthcheck:
      test: ["CMD-SHELL", "pg_isready -U sypnia"]
      interval: 5s
      retries: 20

  minio:
    image: minio/minio
    restart: unless-stopped
    command: server /data
    environment:
      MINIO_ROOT_USER: sypnia
      MINIO_ROOT_PASSWORD: ${MINIO_PASSWORD}
    volumes: ["bucket:/data"]

  bucket:
    image: minio/mc
    depends_on: [minio]
    environment:
      MINIO_PASSWORD: ${MINIO_PASSWORD}
    entrypoint: >
      sh -c "until mc alias set local http://minio:9000 sypnia $$MINIO_PASSWORD; do sleep 1; done;
             mc mb --ignore-existing local/sypnia"

  caddy:
    image: caddy:2
    restart: unless-stopped
    ports: ["80:80", "443:443"]
    environment:
      SYPNIA_DOMAIN: ${SYPNIA_DOMAIN}
      STORAGE_DOMAIN: ${STORAGE_DOMAIN}
    volumes:
      - ./Caddyfile:/etc/caddy/Caddyfile:ro
      - caddy:/data
    depends_on: [sypnia, minio]

volumes:
  db:
  bucket:
  caddy:
```

Every `SYPNIA_…` line is a setting of the [configuration reference](https://docs.sypnia.com/self-hosting/configuration). Three of them differ from the quickstart, and each matters:

- `SYPNIA_BASE_URL` is the public HTTPS address. It is written into links, and it is where the Console lives.
- `SYPNIA_TRUSTED_PROXY_HOPS` is `1` because one proxy, Caddy, stands in front of the engine. With `0` every visitor would share one rate limit: Caddy's address.
- `SYPNIA_STORAGE_PUBLIC_ENDPOINT` is the address browsers use for the store. The engine itself keeps using `http://minio:9000`, inside the Compose network.

`SYPNIA_AUTO_MIGRATE` is `true` so the engine creates and updates its tables when it starts. That is right for one process. If you later [run several](https://docs.sypnia.com/self-hosting/scaling-and-cost#from-one-process-to-several), set it to `false` and run `sypnia migrate` as a step of your deploy.

### 4. Write the Caddy file

`Caddyfile`

```text
{$SYPNIA_DOMAIN} {
	reverse_proxy sypnia:8080
}

{$STORAGE_DOMAIN} {
	reverse_proxy minio:9000
}
```

Any reverse proxy or load balancer with TLS works in Caddy's place. It must pass the `Host` header through unchanged to the store, or signed links stop matching.

### 5. Start it

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

**You should see:**`sypnia`, `db`, `minio` and `caddy` with the status `running`. `bucket` is not in the list: it created the bucket and exited.

### 6. Check its health

```bash
curl -i https://sypnia.example.com/healthz
```

**You should see:**`HTTP/2 200`. The first time, give Caddy up to a minute to get the certificates. `/healthz` answers `200` when the process is up and serving; point your load balancer or your own monitor at it. It does not test the database or the bucket: `sypnia doctor`, in the next step, does.

### 7. Run the doctor

```bash
docker compose exec sypnia sypnia doctor --skip ai
```

**You should see:**

```text
config    ok    11 settings read, 0 unknown
database  ok    postgres 16.4, schema 12 (up to date), 2 ms
storage   ok    s3://sypnia: put, get, delete, presign
address   ok    https://sypnia.example.com/healthz answered 200
webhook   skip  SYPNIA_ALERT_WEBHOOK_URL is not set (alerts are recorded only)
clock     ok    0.1 s from the database's clock
all checks passed
```

A line that says `FAIL` names the setting to change. The AI check is skipped because no model is connected yet.

### 8. Create the first project

```bash
docker compose exec sypnia sypnia project create --name Shop
```

**You should see:**

```text
project     shop (prj_5k2m9x4q7w1z)
ingest key  spk_7d1f0c9e4b8a2f6d3c5e1a9b0f4d8c2e

Put the ingest key in your app. It is public: it can only send.
Next: sypnia token create --project shop --name "My laptop" --scopes read,replay
```

The command uses the root token it finds in the container's environment. The ingest key it prints is the one your browser app sends with.

### 9. Create a key for each other app, and a token to read

Give your server its own ingest key, so you can revoke one without stopping the other:

```bash
docker compose exec sypnia sypnia key create --project shop --name "Checkout API"
```

**You should see:**

```text
key_8b5n2m7v4c1x  spk_a3c9e1f7b5d2084c6e0a9f3b7d1c5e82  Checkout API
```

Then an API token, to read what arrives from the Console, the CLI or your coding agent:

```bash
docker compose exec sypnia sypnia token create --project shop --name "My laptop" --scopes read,replay
```

**You should see:**A line that starts with `sps_`. It is shown once: copy it now. It is a secret.

### 10. Send from your app and see it arrive

Point the SDK at your engine with `endpoint`:

`src/main.ts`

```ts
import { init } from '@sypnia/browser';

init({
  project: 'spk_7d1f0c9e4b8a2f6d3c5e1a9b0f4d8c2e',
  endpoint: 'https://sypnia.example.com',
  environment: location.hostname === 'localhost' ? 'development' : 'production',
});
```

Open your app, click on a few things, then open `https://sypnia.example.com/console` and paste your API token.

**You should see:**Within 10 minutes, your session in the Console. Within 2 minutes of a first error, a problem. [Your first problem](https://docs.sypnia.com/start/your-first-problem) walks through causing one on purpose.

Before real traffic, go through the [security checklist](https://docs.sypnia.com/self-hosting/security-checklist) and set up [backups](https://docs.sypnia.com/self-hosting/upgrades-backups-retention).

## Use a hosted bucket or database

The Compose file above keeps everything on one server. Each store can live somewhere else instead; the engine only needs its address. Change the settings, remove the service you no longer need from `compose.yaml` (and its line in `depends_on`), and run `docker compose up -d`.

### Amazon S3

Remove `minio`, `bucket`, the second site in the `Caddyfile` and the second DNS name. Replace the `SYPNIA_STORAGE_…` lines with:

```yaml
      SYPNIA_STORAGE_BUCKET: <your bucket>
      SYPNIA_STORAGE_REGION: us-east-1
      SYPNIA_STORAGE_ACCESS_KEY_ID: ${S3_ACCESS_KEY_ID}
      SYPNIA_STORAGE_SECRET_ACCESS_KEY: ${S3_SECRET_ACCESS_KEY}
```

On a server inside AWS with a role, leave the two key lines out: the engine uses the role. The key or the role needs to read, write, list and delete in that one bucket and nothing else.

### Cloudflare R2

The same as Amazon S3, with the endpoint of your account and the region `auto`:

```yaml
      SYPNIA_STORAGE_BUCKET: <your bucket>
      SYPNIA_STORAGE_REGION: auto
      SYPNIA_STORAGE_ENDPOINT: https://<account id>.r2.cloudflarestorage.com
      SYPNIA_STORAGE_ACCESS_KEY_ID: ${R2_ACCESS_KEY_ID}
      SYPNIA_STORAGE_SECRET_ACCESS_KEY: ${R2_SECRET_ACCESS_KEY}
```

### Let browsers read replays from a hosted bucket

The Console plays a replay by fetching its chunks from the bucket, in your browser, through signed links. A hosted bucket refuses that until you allow your engine's address to read. MinIO needs nothing: it answers any origin.

`cors.json`

```json
{
  "CORSRules": [
    {
      "AllowedOrigins": ["https://sypnia.example.com"],
      "AllowedMethods": ["GET"],
      "AllowedHeaders": ["*"],
      "MaxAgeSeconds": 3600
    }
  ]
}
```

```bash
aws s3api put-bucket-cors --bucket <your bucket> --cors-configuration file://cors.json
```

For Cloudflare R2, add the same rule in the bucket's settings, or run the same command with `--endpoint-url https://<account id>.r2.cloudflarestorage.com`. The bucket itself stays private: the rule lets a browser use a signed link, it does not let anyone read without one.

### A hosted Postgres

Remove `db` and its volume, and set the connection string. Add `?sslmode=require`, because the database is no longer on the same machine.

```yaml
      SYPNIA_DATABASE_URL: ${DATABASE_URL}
```

| Provider                                      | Which connection string                                                                                                  |
| --------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------ |
| Supabase                                      | The session-mode one, on port 5432. The engine keeps a few connections open and runs transactions of several statements. |
| Neon                                          | The direct one, not the pooled one.                                                                                      |
| Amazon RDS, or any other Postgres 15 or later | The instance's own address.                                                                                              |

Give Sypnia a database of its own. Do not share the one your app uses: the engine's work would compete with your app's for memory and connections.

## Day to day

| To                        | Run                                                                                                                                                                      |
| ------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| Read the engine's log     | `docker compose logs -f sypnia`                                                                                                                                          |
| Apply a changed setting   | Edit `compose.yaml` or `.env`, then `docker compose up -d`. Settings are read at start.                                                                                  |
| Check everything again    | `docker compose exec sypnia sypnia doctor`                                                                                                                               |
| Update the engine         | `docker compose pull sypnia && docker compose up -d sypnia`. Read [Upgrades, backups, retention](https://docs.sypnia.com/self-hosting/upgrades-backups-retention) first. |
| Stop it, keeping the data | `docker compose down`                                                                                                                                                    |
| Start it at boot          | Nothing: `restart: unless-stopped` does it, as long as Docker itself starts at boot.                                                                                     |

Stopping is clean: on `docker compose down` the engine finishes the requests in flight, for up to 20 seconds, and the worker finishes its current step. Compose waits 10 seconds by default before it kills a container, so add `stop_grace_period: 30s` to the `sypnia` service if you want the full 20. A killed worker loses nothing either way: processing is safe to repeat.

## Remove everything

```bash
docker compose down -v
```

> **Warning**
>
> `-v` deletes the volumes: the database, the bucket and the certificates. Nothing can bring them back. Without `-v` the data stays on the server for the next `docker compose up -d`.

Then delete the folder with `.env`, the two DNS records, and, if you used a hosted bucket or database, those too.

## Troubleshooting

| What you see                                                                   | Why                                                                                                        | What to do                                                                                                                                       |
| ------------------------------------------------------------------------------ | ---------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------ |
| `sypnia` restarts in a loop; its log names a setting and ends with exit code 3 | A required setting is missing or invalid.                                                                  | Fix the line it names in `compose.yaml` or `.env`.                                                                                               |
| `curl` reports a certificate error                                             | Caddy could not get a certificate: the name does not point at this server, or ports 80 and 443 are closed. | `docker compose logs caddy` says which. Fix DNS or the firewall, then `docker compose restart caddy`.                                            |
| `doctor` says `address FAIL`                                                   | The engine cannot reach its own public address.                                                            | Check that `SYPNIA_DOMAIN` is the name in DNS and that the server can resolve it.                                                                |
| `doctor` says `storage FAIL … presign`                                         | `SYPNIA_STORAGE_PUBLIC_ENDPOINT` is wrong or not reachable.                                                | It must be the HTTPS address of the store as a browser reaches it.                                                                               |
| A replay does not play and the browser's console shows a `403` from the store  | The proxy changed the `Host` header, or the store's clock is off.                                          | Pass `Host` through unchanged. Check the server's clock.                                                                                         |
| A replay does not play and the browser's console shows a CORS error            | A hosted bucket without the rule.                                                                          | Add [the rule](#let-browsers-read-replays-from-a-hosted-bucket).                                                                                 |
| Every visitor gets `429` together                                              | `SYPNIA_TRUSTED_PROXY_HOPS` is `0` behind a proxy.                                                         | Set it to the number of proxies in front of the engine.                                                                                          |
| The disk fills                                                                 | Recordings are most of what the engine stores.                                                             | Lower `SYPNIA_RETENTION_REPLAYS_DAYS` or `SYPNIA_REPLAY_SAMPLE_RATE`. See [Storage layout](https://docs.sypnia.com/self-hosting/storage-layout). |

## Next
