Skip to content
DashboardWebsite

Deployment

This page helps platform administrators choose a self-hosted OpenTremor deployment. Docker Compose runs on one host; the Helm chart runs on Kubernetes.

TopologyBest for
Docker (Single-VM)One host, no Kubernetes cluster — Compose + HAProxy + Let’s Encrypt
Helm chartKubernetes — HPA, Ingress, Secret management

The Helm chart is maintained in the separate OpenTremor Deployments repo. See Helm deployment for its setup instructions.


DependencyRequiredNotes
Docker + Compose, or a Kubernetes clusterYesChoose based on the deployment topology
MongoDBYesThe only storage backend. Docker Compose includes MongoDB 7.0. The Helm chart’s bundled MongoDB is for development only; production needs a reachable MongoDB instance.

Both topologies use OpenTremor’s YAML configuration fields. See Full Reference for the fields. The Helm chart can generate the config file from chart values.

For a real deployment, set JWT_SECRET, SECRETS_ENCRYPTION_KEY and TWO_FACTOR_SECRET_KEY explicitly through environment variables or a Secret. If unset, each defaults to a new random value per process. The service can start, but a restart or another replica can make sessions or encrypted data inaccessible:

UnsetWhat breaks
JWT_SECRETExisting sessions stop working; users must log in again
SECRETS_ENCRYPTION_KEYStored secrets become unreadable, including per-org LLM credentials, SSO client secrets, notification channel secrets, and a custom GitHub App’s private key and webhook secret. The App’s webhooks fail until it is re-registered.
TWO_FACTOR_SECRET_KEYEnrolled TOTP secrets become unreadable; users with 2FA must enrol again

Keep these keys stable. Changing JWT_SECRET invalidates existing sessions; changing SECRETS_ENCRYPTION_KEY makes secrets encrypted with its previous value unreadable, and they must be re-entered; changing TWO_FACTOR_SECRET_KEY makes enrolled TOTP secrets unreadable, so users with 2FA must enrol again. The codebase has no re-encryption step for encrypted secrets.

The make up-prod command reads these keys from .env.prod at the workspace root, using the keys listed in OpenTremor-deployments/.env.example. The Compose stack refuses to start if any is missing.

AUTH_API_KEY is also required by that Compose stack. The .env.example snippet generates it alongside the other three keys. It is not an encryption key and can be rotated. If unset, authentication is disabled and every caller resolves to a superadmin owner of the default org. See Environment Variables. The GitHub App integration needs no deployment setting beyond server.public_base_url; each organization registers its own App.