Docs

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 Engine At launch

View as Markdown
On this page
  1. What runs
  2. Deploy
  3. Point two names at the server
  4. Write the secrets
  5. Write the Compose file
  6. Write the Caddy file
  7. Start it
  8. Check its health
  9. Run the doctor
  10. Create the first project
  11. Create a key for each other app, and a token to read
  12. Send from your app and see it arrive
  13. Use a hosted bucket or database
  14. Amazon S3
  15. Cloudflare R2
  16. Let browsers read replays from a hosted bucket
  17. A hosted Postgres
  18. Day to day
  19. Remove everything
  20. Troubleshooting
  21. 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

ServiceImageWhat it doesReachable from outside
sypniaghcr.io/sypnia/sypnia:1The whole engine in one process: sypnia serve with the role all.Only through caddy
dbpostgres:16The database.No
miniominio/minioThe S3-compatible store that holds the bucket.Only through caddy, for replay links and source-map uploads
bucketminio/mcCreates the bucket once, then exits.No
caddycaddy:2HTTPS 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

  1. Point two names at the server

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

    NameFor
    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.com
    You should see
    The server’s address, twice.
  2. 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 .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
    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_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, set it to false and run sypnia migrate as a step of your deploy.

  4. Write the Caddy file

    Caddyfile
    {$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

    Terminal
    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

    Terminal
    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

    Terminal
    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

    Terminal
    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:

    Terminal
    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:

    Terminal
    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
    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 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:

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
{
  "CORSRules": [
    {
      "AllowedOrigins": ["https://sypnia.example.com"],
      "AllowedMethods": ["GET"],
      "AllowedHeaders": ["*"],
      "MaxAgeSeconds": 3600
    }
  ]
}
Terminal
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}
ProviderWhich connection string
SupabaseThe session-mode one, on port 5432. The engine keeps a few connections open and runs transactions of several statements.
NeonThe direct one, not the pooled one.
Amazon RDS, or any other Postgres 15 or laterThe 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

ToRun
Read the engine’s logdocker compose logs -f sypnia
Apply a changed settingEdit compose.yaml or .env, then docker compose up -d. Settings are read at start.
Check everything againdocker compose exec sypnia sypnia doctor
Update the enginedocker compose pull sypnia && docker compose up -d sypnia. Read Upgrades, backups, retention first.
Stop it, keeping the datadocker compose down
Start it at bootNothing: 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

Terminal
docker compose down -v

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

Troubleshooting

What you seeWhyWhat to do
sypnia restarts in a loop; its log names a setting and ends with exit code 3A required setting is missing or invalid.Fix the line it names in compose.yaml or .env.
curl reports a certificate errorCaddy 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 FAILThe 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 … presignSYPNIA_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 storeThe 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 errorA hosted bucket without the rule.Add the rule.
Every visitor gets 429 togetherSYPNIA_TRUSTED_PROXY_HOPS is 0 behind a proxy.Set it to the number of proxies in front of the engine.
The disk fillsRecordings are most of what the engine stores.Lower SYPNIA_RETENTION_REPLAYS_DAYS or SYPNIA_REPLAY_SAMPLE_RATE. See Storage layout.

Next

Sections

Start hereWhat Sypnia is, how it works, what is open source and what is the paid cloud, and the two ways to get your first problem in plain words.ConceptsThe ten ideas Sypnia is made of, each defined precisely, from a project and its keys to problems, traces and alerts.SDKsHow your app sends data to Sypnia. One SDK for the browser, one for Node, one for Next.js, and the OpenTelemetry intake for every other backend.The agentHow Sypnia analyses a problem, what it writes, what it sends to a model and what it never does.MCP and skillsConnect your coding agent to Sypnia so it can ask what is failing in production, read what it needs to fix it, and set Sypnia up for you.API referenceThe Sypnia HTTP API: one API for the open-source engine and for Sypnia Cloud, with every endpoint, parameter, response and error.CLI referenceThe sypnia command: how to install it, the variables it reads, what its exit codes mean, and where each command is documented.Self-hostingWhat you run when you host the Sypnia engine yourself, what you need, what it costs, and what you do not get compared with Sypnia Cloud.How the engine is builtThe whole Sypnia engine on one page, from a click in your app to the sentence your coding agent reads, with the design rules and the code that holds them.Sypnia CloudHow the paid service works, from organizations and roles to plans, limits, billing, where your data lives, the GitHub App and support.Privacy and securityWhat Sypnia collects from your app and its users, what it never collects, how masking works, how to delete data, and how the service is protected.LicensingWhich licence covers each part of Sypnia, what you may do with it, how the name may be used, and the terms of a contribution.GuidesStep-by-step recipes for the common ways to use Sypnia, from apps made with AI builders and Next.js on Vercel to Supabase, source maps in CI, alert e-mails from your own engine, and moving from Sentry.ReferenceThe pages you look things up in, from the event schema and the glossary to what is planned, the changelog and the common questions.
↑↓ to move↵ to openEsc to close