Docker (Single VM)
This page explains how a platform administrator installs and upgrades a self-hosted OpenTremor instance on one Linux host with Docker Compose. For local development, see Quick Start. For Kubernetes, see the Helm chart.
Choose a Compose file
Section titled “Choose a Compose file”OpenTremor-deployments provides three Compose files. This page covers the single-host production stack.
docker-compose.yaml | docker-compose.dev.yaml | docker-compose.prod.yaml | |
|---|---|---|---|
| Use for | Local evaluation | Live code editing | A single-host installation |
| Start with | make up | docker compose -f OpenTremor-deployments/docker-compose.dev.yaml up | Four one-time steps, below |
| Project name | opentremor | opentremor-dev | opentremor-prod |
| Core | Built image opentremor-core-test:latest; dependencies are baked in at build | uv image over bind-mounted repos; uv run installs from core’s uv.lock at container start | Built image opentremor-core-prod:latest, using the same Dockerfile as quickstart |
| Dashboard | next build baked into opentremor-dashboard:latest | node:24-slim, npm run dev, live reload | opentremor-dashboard-prod:latest, built domain-rooted rather than path-prefixed |
| Docs | Static Starlight build behind nginx | npm run dev --host | Static build behind nginx |
| Task scheduler | Absent | Present | Present |
| Editing source | Needs a rebuild (--build) | Picked up live | Needs a rebuild |
| First boot | Slow — three images build | Slow — uv and npm install, then cached in named volumes | Slow — four images build |
| Routing | Path-routed under one localhost origin (OpenTremor-deployments/haproxy/dev.cfg) | Same | One subdomain per service, with TLS (OpenTremor-deployments/haproxy/prod.cfg) |
| HAProxy | 8080 | 8080 | 80, 8080, and 443 |
| Core published | 8000 | 8001 | Not published |
| MongoDB published | 27017 | 27018 | Not published |
| Dashboard / docs published | 3001 / 4321 | 3001 / 4321 | Not published |
Trusted proxies (TRUSTED_PROXIES, see network) | 172.30.10.0/24, the stack’s pinned subnet | 172.30.11.0/24 | 172.30.12.0/24 |
| MongoDB data | data/quickstart/mongodb | data/dev/mongodb | data/mongodb |
| Network access | Dashboard and docs ask core for a verdict; ./network-lists holds file address lists | Dashboard only (the dev docs server has no nginx); ./network-lists | Same as quickstart |
| Configuration | OpenTremor-deployments/configs/opentremor-local.yaml | Same file | OpenTremor-core/configs/opentremor-core-prod.yaml |
| Secrets | None: dev credentials live in the config file | Same | .env.prod at the workspace root is required; the stack refuses to start without JWT_SECRET, SECRETS_ENCRYPTION_KEY, TWO_FACTOR_SECRET_KEY, and AUTH_API_KEY |
| Restart policy | None | None | unless-stopped on every service |
| TLS | None | None | Let’s Encrypt, requested once and renewed unattended |
The two local stacks publish the same HAProxy, dashboard, and docs ports. Stop one before starting the other.
What the production stack runs
Section titled “What the production stack runs”The production Compose file runs MongoDB, core, the task scheduler, the platform MCP, dashboard, docs, and HAProxy. It also runs Certbot services for issuing and renewing TLS certificates. HAProxy is the only service that publishes host ports.
All services run in OpenTremor-deployments, checked out beside OpenTremor-core, the pack repos, OpenTremor-dashboard, and OpenTremor-docs.
The stack serves the API, docs, dashboard, and MCP on separate subdomains. The default domains in the Compose file and HAProxy configuration include api.opentremor.dev, docs.opentremor.dev, app.opentremor.dev, mcp.opentremor.dev, and opentremor.dev. Change the domains in the Compose file, HAProxy configuration, and core settings to match your installation.
The bare domain serves an operator-provided website when one is attached to the Compose network. Without that service, HAProxy redirects requests to the dashboard subdomain. To attach a website, give its Compose service the name website, serve HTTP on port 3000, and join the production network:
services: website: build: . networks: [opentremor]networks: opentremor: external: true name: opentremor-prod_defaultThe production network is opentremor-prod_default. HAProxy sends requests to the website once it passes a health check. Without a site, requests to the bare domain get a temporary (302) redirect to app.example.com, preserving the path. On that network, the website can reach the API at http://opentremor-core:8000.
Prerequisites
Section titled “Prerequisites”- A Linux host with Docker and Docker Compose.
- DNS records for the API, docs, dashboard, and bare domain pointing to the host’s public IP.
- Host ports
80and443available. Let’s Encrypt must reach port80for the HTTP-01 challenge.
Install
Section titled “Install”1. Configure core and secrets
Section titled “1. Configure core and secrets”Configure OpenTremor-core/configs/opentremor-core-prod.yaml. Follow its header comments for settings that can be supplied through environment variables. At minimum, set auth.api_key through AUTH_API_KEY in .env.prod, and set cors.allow_origins to your dashboard’s real origin, for example https://app.example.com. Credentialed requests cannot use *; the bare domain does not serve the dashboard and needs no CORS entry.
Prefer environment variables or an untracked env file over editing secrets directly into YAML when an environment variable override exists. These include MONGODB_URI, JWT_SECRET, SECRETS_ENCRYPTION_KEY, DEFAULT_ADMIN_EMAIL, and DEFAULT_ADMIN_PASSWORD.
The production stack sets SERVER_COOKIE_DOMAIN for its default domain. Change it to the shared parent domain used by your API and dashboard, such as .example.com. Since the dashboard and API use different origins, the shared cookie domain lets the dashboard’s server-side requests access the session cookie set at login. See Dashboard Deployment for the full explanation.
Put the secrets in one file at the workspace root. Every service in the stack reads it:
cp OpenTremor-deployments/.env.example .env.prodFill in JWT_SECRET, SECRETS_ENCRYPTION_KEY, TWO_FACTOR_SECRET_KEY, and AUTH_API_KEY. Compose refuses to start if any is empty. Keep the first three stable across restarts; changing them makes existing sessions or encrypted data unusable. AUTH_API_KEY can be rotated. DEFAULT_ADMIN_EMAIL and DEFAULT_ADMIN_PASSWORD are optional and seed the initial superadmin account on first boot.
2. Start the stack
Section titled “2. Start the stack”From the workspace root, run:
make up-prodThe workspace Makefile reads .env.prod at the workspace root and checks that the production network uses the pinned subnet 172.30.12.0/24. If an existing network has a different subnet, it stops and prints the commands needed to recreate it.
HAProxy starts with a temporary self-signed certificate so it can bind to port 443 before Let’s Encrypt issues a certificate.
3. Request certificates
Section titled “3. Request certificates”Edit the email address and domain names in the certbot-init service in OpenTremor-deployments/docker-compose.prod.yaml. Then run this one-time command:
docker compose -f OpenTremor-deployments/docker-compose.prod.yaml --profile init run --rm certbot-initAfter issuance, haproxy-reloader detects the certificates on its next check. To reload them immediately, run:
docker compose -f OpenTremor-deployments/docker-compose.prod.yaml restart haproxy-reloaderKeep certificate issuance separate from routine startup. Repeated test requests can hit Let’s Encrypt rate limits.
4. Set the public API and dashboard URLs
Section titled “4. Set the public API and dashboard URLs”In the dashboard: Platform Admin → System → General.
After the stack starts, set both public URLs through the API. Use the API domain and the dashboard domain for your installation:
curl -X PATCH https://api.example.com/v1/admin/settings \ -H "X-API-Key: <bootstrap-api-key>" \ -H "Content-Type: application/json" \ -d '{"server_public_base_url": "https://api.example.com", "server_dashboard_base_url": "https://app.example.com"}'The public API URL is used for links to API routes. The dashboard URL is used for links to dashboard pages.
Renew certificates
Section titled “Renew certificates”The certbot service runs certbot renew about twice a day. Certbot renews certificates that are within 30 days of expiry. haproxy-reloader detects renewed certificate files and reloads HAProxy.
Upgrade
Section titled “Upgrade”From the workspace root, run:
make up-prodThis rebuilds and replaces the application images. MongoDB data and certificates persist in bind mounts or volumes. Core applies the release’s schema migrations at startup. Read Upgrade and Roll Back before upgrading; releases with a schema migration require restoring a backup to roll back.
Put the stack behind another proxy
Section titled “Put the stack behind another proxy”Core trusts X-Forwarded-For only from addresses listed in TRUSTED_PROXIES. The production stack sets this to its own subnet, 172.30.12.0/24. If another proxy sits in front of the stack, add its IP address or range, separated by commas:
TRUSTED_PROXIES: 172.30.12.0/24,203.0.113.10Without the additional proxy address, core sees that proxy as the caller. Network access rules, API key IP allowlists, and denial events then use the proxy address.
Diagnose “Access check unavailable”
Section titled “Diagnose “Access check unavailable””The dashboard and docs can return 503 when core cannot provide a network access verdict. Inspect the service logs:
docker compose -f OpenTremor-deployments/docker-compose.prod.yaml logs dashboard docs opentremor-core | grep -i 'verdict\|network access'A 404 from core can mean it does not trust the caller. Core logs Network access verdict refused to <address>. Check the production network subnet:
docker network inspect opentremor-prod_default -f '{{range .IPAM.Config}}{{.Subnet}}{{end}}'If the subnet is not 172.30.12.0/24, recreate the network with make down, remove opentremor-prod_default, and run make up-prod. Do not change TRUSTED_PROXIES to match an automatically assigned subnet.
Automatic rebuild on rsync
Section titled “Automatic rebuild on rsync”If you sync the workspace to the production host, OpenTremor-deployments/scripts/autodeploy.sh can rebuild and redeploy changed services. The build and production host must be the same machine. Install it once. The full steps, including the systemd units, are in OpenTremor-deployments/systemd/README.md:
sudo mkdir -p /var/lib/opentremor-autodeploysudo chown $RSYNC_USER /var/lib/opentremor-autodeploysudo STATE_DIR=/var/lib/opentremor-autodeploy /srv/opentremor/OpenTremor-deployments/scripts/autodeploy.sh --seedsudo cp /srv/opentremor/OpenTremor-deployments/systemd/opentremor-autodeploy.{path,service} /etc/systemd/system/sudo systemctl daemon-reloadsudo systemctl enable --now opentremor-autodeploy.pathThe script watches a sentinel file, not the synced tree. Touch the sentinel only after a successful transfer:
rsync -az --delete ~/opentremor/ buildserver:/srv/opentremor/ \ && ssh buildserver 'touch /var/lib/opentremor-autodeploy/rsync-done'The -a option preserves modification times, which the default change detection uses. If you cannot preserve modification times, set FINGERPRINT_MODE=content in the service unit.
Each service is fingerprinted over its build inputs, so only affected images are rebuilt. Changes to a pack repo rebuild both core and docs; changes to dashboard rebuild the dashboard; changes to the HAProxy config restart HAProxy without rebuilding it. certbot-init does not run during automatic deploys. Request certificates manually using step 3.
A failed build leaves the running containers in place. If a service fails its health check, autodeploy rolls back the services deployed in that pass, except core after it has started schema migrations. State advances only after a healthy deploy, so the next sync retries the same changes.
journalctl -fu opentremor-autodeploy # follow a runOpenTremor-deployments/scripts/autodeploy.sh --dry-run # report what would rebuildBack up data
Section titled “Back up data”MongoDB holds the live database. Do not copy data/mongodb while MongoDB is running as a backup.
In the dashboard: Platform Admin → System → Backups. Set the encryption key under Encryption key, or set BACKUP_AGE_RECIPIENTS in .env.prod, then configure the schedule and target under Schedule & storage. See Backups and Restore for setup, key storage, and restore steps.
The production stack also stores certificates under data/certbot. Certbot can issue them again. The backups volume stores backups made with the local target. The containers are stateless and disposable.