Deployment (Docker)¶

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

Architecture¶

graph LR
    User["Browser"]
    Web["web<br/><small>caddy:8080</small><br/><small>UID 65532</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¶

Persistence, queue, and observability (CFG-1 audit)¶

These environment variables are read by the code but were previously undocumented. Setting any of them requires a container restart.

Settings-registry env vars¶

Every registered setting automatically accepts an env-var override of the form SYNTHORG_<NAMESPACE>_<KEY>, where <NAMESPACE> and <KEY> are the registered setting's namespace and key uppercased (they are not derived from the setting's yaml_path). For example, setting SYNTHORG_API_CORS_ALLOWED_ORIGINS='["http://localhost:5173"]' overrides the CORS origin list for the current process. See Settings Reference for the full catalog.

Resolution chain (first match wins, in synthorg.telemetry.collector._resolve_environment):

1. SYNTHORG_TELEMETRY_ENV (operator override): always wins if non-empty.
2. CI auto-detection: CI / GITLAB_CI / BUILDKITE / JENKINS_URL / any RUNPOD_* present -> "ci".
3. SYNTHORG_TELEMETRY_ENV_BAKED (image-baked fallback): set by CI via DEPLOYMENT_ENV build-arg; see above.
4. The parsed TelemetryConfig.environment value, which itself defaults to "dev" when not configured.

Image build-args¶

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.

Health Probes¶

Three distinct health endpoints live in this deployment; don't conflate them.

The backend endpoints are unauthenticated so load-balancers and container orchestrators can probe them without credentials. Both are pinned in the OpenAPI schema.

Container Details¶

Backend¶

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

Web¶

• Base image: Pure apko Wolfi (Caddy + melange-packaged static assets, no Dockerfile)
• User: UID 65532 (caddy)
• Health check: GET /healthz via Caddy, Caddy's own built-in liveness endpoint (distinct from the backend's /api/v1/healthz, see Health Probes above). Compose-level probe using wget; 10s interval, 3s timeout, 3 retries, 10s start period. The apko image intentionally ships no Dockerfile HEALTHCHECK, so the probe is declared alongside the service and targets 127.0.0.1 to avoid Docker DNS.
• Routing: SPA routing (try_files {path} /index.html), API proxy to backend, WebSocket proxy, per-request CSP nonce via Caddy templates directive
• 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 file_server { precompressed gzip }

Security Hardening¶

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

Security Headers (Caddy)¶

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'; script-src 'self'; style-src 'self' 'nonce-{http.request.uuid}' 'unsafe-inline'; style-src-elem 'self' 'nonce-{http.request.uuid}'; style-src-attr 'unsafe-inline'; connect-src 'self'; img-src 'self' data:; font-src 'self'; object-src 'none'; base-uri 'self'; form-action 'self'; frame-ancestors 'none'
• Strict-Transport-Security: max-age=63072000 (2 years)

The CSP uses Level 3 directive splitting: style-src-elem locks <style> elements to the per-request nonce (injected by Caddy's templates directive substituting {http.request.uuid} into <meta name="csp-nonce">), while style-src-attr 'unsafe-inline' covers the transient inline positioning styles set by Floating UI (used internally by Base UI). See docs/security.md → CSP Nonce Infrastructure for the full flow; any reverse proxy in front of the web container must preserve Caddy's template substitution and the matching CSP header, otherwise inline styles will be blocked.

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

Fine-Tuning (optional)¶

Embedding fine-tuning runs in a dedicated ephemeral container that the backend spawns on demand. It is disabled by default because the image is large and the workload is heavy.

Two image variants ship from GHCR, both amd64-only:

Fine-tuning also requires the sandbox to be enabled (sandbox=true). The backend launches each pipeline stage in a one-shot container using the Docker API.

synthorg config set sandbox true
synthorg config set fine_tuning true
synthorg config set fine_tuning_variant gpu   # or: cpu
synthorg stop && synthorg start               # compose.yml is regenerated automatically

services:
  backend:
    environment:
      # Backend reads this on demand to spawn fine-tune containers via
      # the Docker API. Point at a digest-pinned ref for reproducibility.
      SYNTHORG_FINE_TUNE_IMAGE: ghcr.io/aureliolo/synthorg-fine-tune-gpu:${SYNTHORG_IMAGE_TAG:-latest}
  fine-tune:
    image: ghcr.io/aureliolo/synthorg-fine-tune-gpu:${SYNTHORG_IMAGE_TAG:-latest}
    # For CPU-only hosts, swap to: ghcr.io/aureliolo/synthorg-fine-tune-cpu
    volumes:
      - synthorg-data:/data:ro
    depends_on:
      backend:
        condition: service_healthy
    user: "10003:10003"
    group_add: ["65532"]
    security_opt: [no-new-privileges:true]
    cap_drop: [ALL]
    read_only: true

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