Deployment
This page helps platform administrators choose a self-hosted OpenTremor deployment. Docker Compose runs on one host; the Helm chart runs on Kubernetes.
| Topology | Best for |
|---|---|
| Docker (Single-VM) | One host, no Kubernetes cluster — Compose + HAProxy + Let’s Encrypt |
| Helm chart | Kubernetes — HPA, Ingress, Secret management |
The Helm chart is maintained in the separate OpenTremor Deployments repo. See Helm deployment for its setup instructions.
Runtime dependencies
Section titled “Runtime dependencies”| Dependency | Required | Notes |
|---|---|---|
| Docker + Compose, or a Kubernetes cluster | Yes | Choose based on the deployment topology |
| MongoDB | Yes | The 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. |
Configuration
Section titled “Configuration”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:
| Unset | What breaks |
|---|---|
JWT_SECRET | Existing sessions stop working; users must log in again |
SECRETS_ENCRYPTION_KEY | Stored 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_KEY | Enrolled 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.