Skip to content
DashboardWebsite

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.

OpenTremor-deployments provides three Compose files. This page covers the single-host production stack.

docker-compose.yamldocker-compose.dev.yamldocker-compose.prod.yaml
Use forLocal evaluationLive code editingA single-host installation
Start withmake updocker compose -f OpenTremor-deployments/docker-compose.dev.yaml upFour one-time steps, below
Project nameopentremoropentremor-devopentremor-prod
CoreBuilt image opentremor-core-test:latest; dependencies are baked in at builduv image over bind-mounted repos; uv run installs from core’s uv.lock at container startBuilt image opentremor-core-prod:latest, using the same Dockerfile as quickstart
Dashboardnext build baked into opentremor-dashboard:latestnode:24-slim, npm run dev, live reloadopentremor-dashboard-prod:latest, built domain-rooted rather than path-prefixed
DocsStatic Starlight build behind nginxnpm run dev --hostStatic build behind nginx
Task schedulerAbsentPresentPresent
Editing sourceNeeds a rebuild (--build)Picked up liveNeeds a rebuild
First bootSlow — three images buildSlow — uv and npm install, then cached in named volumesSlow — four images build
RoutingPath-routed under one localhost origin (OpenTremor-deployments/haproxy/dev.cfg)SameOne subdomain per service, with TLS (OpenTremor-deployments/haproxy/prod.cfg)
HAProxy8080808080, 8080, and 443
Core published80008001Not published
MongoDB published2701727018Not published
Dashboard / docs published3001 / 43213001 / 4321Not published
Trusted proxies (TRUSTED_PROXIES, see network)172.30.10.0/24, the stack’s pinned subnet172.30.11.0/24172.30.12.0/24
MongoDB datadata/quickstart/mongodbdata/dev/mongodbdata/mongodb
Network accessDashboard and docs ask core for a verdict; ./network-lists holds file address listsDashboard only (the dev docs server has no nginx); ./network-listsSame as quickstart
ConfigurationOpenTremor-deployments/configs/opentremor-local.yamlSame fileOpenTremor-core/configs/opentremor-core-prod.yaml
SecretsNone: dev credentials live in the config fileSame.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 policyNoneNoneunless-stopped on every service
TLSNoneNoneLet’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.

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_default

The 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.

  • 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 80 and 443 available. Let’s Encrypt must reach port 80 for the HTTP-01 challenge.

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:

Terminal window
cp OpenTremor-deployments/.env.example .env.prod

Fill 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.

From the workspace root, run:

Terminal window
make up-prod

The 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.

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:

Terminal window
docker compose -f OpenTremor-deployments/docker-compose.prod.yaml --profile init run --rm certbot-init

After issuance, haproxy-reloader detects the certificates on its next check. To reload them immediately, run:

Terminal window
docker compose -f OpenTremor-deployments/docker-compose.prod.yaml restart haproxy-reloader

Keep certificate issuance separate from routine startup. Repeated test requests can hit Let’s Encrypt rate limits.

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:

Terminal window
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.

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.

From the workspace root, run:

Terminal window
make up-prod

This 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.

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.10

Without 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.

The dashboard and docs can return 503 when core cannot provide a network access verdict. Inspect the service logs:

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

Terminal window
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.

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:

Terminal window
sudo mkdir -p /var/lib/opentremor-autodeploy
sudo chown $RSYNC_USER /var/lib/opentremor-autodeploy
sudo STATE_DIR=/var/lib/opentremor-autodeploy /srv/opentremor/OpenTremor-deployments/scripts/autodeploy.sh --seed
sudo cp /srv/opentremor/OpenTremor-deployments/systemd/opentremor-autodeploy.{path,service} /etc/systemd/system/
sudo systemctl daemon-reload
sudo systemctl enable --now opentremor-autodeploy.path

The script watches a sentinel file, not the synced tree. Touch the sentinel only after a successful transfer:

Terminal window
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.

Terminal window
journalctl -fu opentremor-autodeploy # follow a run
OpenTremor-deployments/scripts/autodeploy.sh --dry-run # report what would rebuild

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.