Deployment (Docker)¶

SynthOrg runs as two Docker containers -- a Python backend API and an Nginx + React web dashboard. This guide covers production deployment, environment configuration, security hardening, and operations.

Architecture¶

graph LR
    User["Browser"]
    Web["web<br/><small>nginx:8080</small><br/><small>UID 101</small>"]
    Backend["backend<br/><small>uvicorn:3001</small><br/><small>UID 65532</small>"]
    Volume["synthorg-data<br/><small>SQLite + Memory</small>"]

    User -->|":3000"| Web
    Web -->|"/api/* proxy"| Backend
    Web -->|"/api/v1/ws proxy"| Backend
    Backend --> Volume

Quick Deploy¶

synthorg init     # interactive setup wizard
synthorg start    # pull images, verify signatures, start containers
synthorg status   # verify health

git clone https://github.com/Aureliolo/synthorg
cd synthorg
cp docker/.env.example docker/.env
# Edit docker/.env with your secrets (see Environment Variables below)
docker compose -f docker/compose.yml up -d

See the Quickstart Tutorial for a complete walkthrough and the User Guide for all CLI commands.

Environment Variables¶

All environment variables are configured in docker/.env (copy from docker/.env.example):

Required¶

Optional¶

First-Run Setup¶

After the containers are running, open http://localhost:3000. The setup wizard appears on a fresh install. See the User Guide for the full wizard walkthrough.

Container Details¶

Backend¶

• Base image: Chainguard Python distroless (no shell, continuously scanned)
• Build: 3-stage (builder -> setup -> runtime) for minimal attack surface
• User: UID 65532 (distroless non-root)
• Health check: GET /api/v1/health (10s interval, 5s timeout, 3 retries, 30s start period)
• Entry point: uvicorn synthorg.api.app:create_app --factory --no-access-log

Web¶

• Base image: nginxinc/nginx-unprivileged (Alpine-based)
• User: UID 101 (nginx)
• Health check: wget --spider http://127.0.0.1:8080/ (10s interval, 3s timeout, 3 retries)
• Routing: SPA routing (try_files $uri /index.html), API proxy to backend, WebSocket proxy
• Caching: /index.html is no-cache; /assets/* is immutable with 1-year max-age (content-hashed filenames)
• Static compression: pre-compressed .gz files served via gzip_static on

Security Hardening¶

The Docker Compose configuration follows the CIS Docker Benchmark v1.6.0:

Security Headers (Nginx)¶

The web container sets the following response headers:

• X-Content-Type-Options: nosniff
• X-Frame-Options: DENY
• Referrer-Policy: strict-origin-when-cross-origin
• Permissions-Policy: geolocation=(), camera=(), microphone=()
• Content-Security-Policy: default-src 'self'; style-src 'self' 'unsafe-inline'
• Strict-Transport-Security: max-age=63072000 (2 years)

Volumes & Data Persistence¶

The synthorg-data Docker volume persists all application data:

• SQLite database (/data/synthorg.db)
• Agent memory files (/data/memory/)
• Log files (/data/logs/)

Backup¶

synthorg backup             # create a backup
synthorg backup --list       # list available backups
synthorg backup --restore    # restore from backup

For manual Docker Compose deployments, back up the synthorg-data volume directly.

Wipe & Reset¶

synthorg wipe    # offers backup, wipes all data, optionally restarts fresh

Networking¶

Both containers run on the synthorg-net Docker network. The web container proxies API requests to the backend:

• http://localhost:3000/api/* -> http://backend:3001/api/*
• ws://localhost:3000/api/v1/ws -> ws://backend:3001/api/v1/ws

Local LLM Providers¶

To use a local LLM like Ollama running on the host machine, configure the provider with host.docker.internal:

providers:
  local-ollama:
    auth_type: none
    base_url: "http://host.docker.internal:11434"

Image Verification¶

SynthOrg container images are signed with cosign keyless signatures and include SLSA Level 3 provenance attestations.

synthorg start and synthorg update automatically verify signatures before pulling images. If verification fails (e.g. in an air-gapped environment):

synthorg start --skip-verify
# or
export SYNTHORG_SKIP_VERIFY=1
synthorg start

Updates¶

synthorg update    # pull latest images, verify signatures, restart containers

The CLI re-launches itself after binary replacement so the remaining steps use the new version. If the compose template has structural changes, the diff is shown for approval before applying.

Channels¶

synthorg config set channel dev      # opt in to pre-release builds
synthorg config set channel stable   # switch back to stable

Auto-Cleanup¶

Automatically remove old container images after updates (keeps current + previous version):

synthorg config set auto_cleanup true

Production Checklist¶

Troubleshooting¶

Health Check¶

synthorg doctor    # run diagnostics
synthorg status    # check container health
synthorg logs      # view container logs

Common Issues¶

See Also¶

• Quickstart Tutorial -- get started in 5 minutes
• User Guide -- CLI commands and setup wizard
• Security -- security architecture reference
• Company Configuration -- full configuration reference