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.
On this page
- What runs
- Deploy
- Point two names at the server
- Write the secrets
- Write the Compose file
- Write the Caddy file
- Start it
- Check its health
- Run the doctor
- Create the first project
- Create a key for each other app, and a token to read
- Send from your app and see it arrive
- Use a hosted bucket or database
- Amazon S3
- Cloudflare R2
- Let browsers read replays from a hosted bucket
- A hosted Postgres
- Day to day
- Remove everything
- Troubleshooting
- Next
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; for AWS without a server, Deploy on 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); two DNS names that point at it; openssl; about 30 minutes.
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.
Deploy
Point two names at the server
At your DNS provider, create two
Arecords with the server’s address:Name For sypnia.example.comThe engine: SDKs, the API, the MCP server, the Console storage.sypnia.example.comThe store: replay links and source-map uploads Terminal dig +short sypnia.example.com storage.sypnia.example.comYou should seeThe server’s address, twice.Write the secrets
In an empty folder on the server:
Terminal 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 .envYou should seeA file.envwith five lines that only you can read. Copy the root token to your password manager: it can do everything on every project.Write the Compose file
compose.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. Three of them differ from the quickstart, and each matters:SYPNIA_BASE_URLis the public HTTPS address. It is written into links, and it is where the Console lives.SYPNIA_TRUSTED_PROXY_HOPSis1because one proxy, Caddy, stands in front of the engine. With0every visitor would share one rate limit: Caddy’s address.SYPNIA_STORAGE_PUBLIC_ENDPOINTis the address browsers use for the store. The engine itself keeps usinghttp://minio:9000, inside the Compose network.
SYPNIA_AUTO_MIGRATEistrueso the engine creates and updates its tables when it starts. That is right for one process. If you later run several, set it tofalseand runsypnia migrateas a step of your deploy.Check its health
Terminal curl -i https://sypnia.example.com/healthzYou should seeHTTP/2 200. The first time, give Caddy up to a minute to get the certificates./healthzanswers200when 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.Run the doctor
Terminal docker compose exec sypnia sypnia doctor --skip aiYou should seeText 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 passedA line that says
FAILnames the setting to change. The AI check is skipped because no model is connected yet.Create the first project
Terminal docker compose exec sypnia sypnia project create --name ShopYou should seeText 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,replayThe 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.
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:
Terminal docker compose exec sypnia sypnia key create --project shop --name "Checkout API"You should seeText key_8b5n2m7v4c1x spk_a3c9e1f7b5d2084c6e0a9f3b7d1c5e82 Checkout APIThen an API token, to read what arrives from the Console, the CLI or your coding agent:
Terminal docker compose exec sypnia sypnia token create --project shop --name "My laptop" --scopes read,replayYou should seeA line that starts withsps_. It is shown once: copy it now. It is a secret.Send from your app and see it arrive
Point the SDK at your engine with
endpoint:src/main.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/consoleand paste your API token.You should seeWithin 10 minutes, your session in the Console. Within 2 minutes of a first error, a problem. Your first problem walks through causing one on purpose.
Before real traffic, go through the security checklist and set up backups.
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:
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:
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.
{
"CORSRules": [
{
"AllowedOrigins": ["https://sypnia.example.com"],
"AllowedMethods": ["GET"],
"AllowedHeaders": ["*"],
"MaxAgeSeconds": 3600
}
]
}aws s3api put-bucket-cors --bucket <your bucket> --cors-configuration file://cors.jsonFor 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.
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 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
docker compose down -vThen 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. |
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. |
Next
- What to close before real traffic.
- Back up the database before you rely on it.
- What the built-in page shows, and how to protect it.
- Connect a model to get the sentence in plain words.