Helm Chart (Kubernetes)
The Helm chart deploys OpenTremor on any Kubernetes cluster. This page is for operators who install and run it. The chart covers every workload a deployment runs, plus a MongoDB for development:
| Workload | Values flag | What it is |
|---|---|---|
| core | always on | The API — Deployment, Service, config Secret, ServiceAccount, optional Ingress/HPA/PDB/PVC |
| dashboard | dashboard.enabled | The Next.js UI, on its own Deployment+Service |
| docs | docs.enabled | This documentation site, served as static files by nginx |
| task-scheduler | taskScheduler.enabled | The “cron” core doesn’t have — see Task Scheduler |
| mcp | mcp.enabled | The platform MCP: lets an agent manage OpenTremor as its user. Stateless, holds no credential |
| mongodb | mongodb.enabled | A single unauthenticated MongoDB pod, for development only |
The dashboard, docs, task scheduler and MCP are off by default only because each needs an image the chart can pull. A real deployment runs all of them.
Prerequisites
Section titled “Prerequisites”- Kubernetes 1.26+
- Helm 3.12+
- A reachable MongoDB instance (in-cluster or external)
Get the chart
Section titled “Get the chart”Each release publishes a signed chart to GitHub’s container registry, tagged with the release version. Its default image tags point to that release’s images.
helm upgrade --install opentremor oci://ghcr.io/opentremor/charts/opentremor \ --version <release> \ --set config.auth.apiKey="$(openssl rand -base64 32)" \ ...The examples on this page use the chart from a clone of this repo, helm/opentremor. To use the
published chart instead, replace that path with
oci://ghcr.io/opentremor/charts/opentremor --version <release>.
Verify the images and the chart
Section titled “Verify the images and the chart”Every release image and the chart are signed with cosign, without a key. The signature identifies the release workflow that built them. Each image also carries its SPDX SBOM as a signed attestation.
cosign verify ghcr.io/opentremor/opentremor-core:<release> \ --certificate-oidc-issuer https://token.actions.githubusercontent.com \ --certificate-identity-regexp '^https://github.com/opentremor/opentremor/'
cosign verify-attestation --type spdxjson ghcr.io/opentremor/opentremor-core:<release> \ --certificate-oidc-issuer https://token.actions.githubusercontent.com \ --certificate-identity-regexp '^https://github.com/opentremor/opentremor/'The four secrets
Section titled “The four secrets”The chart never creates a credential for you. When one is missing, it refuses to render instead of deploying something insecure. Prepare these four before the first install.
1. config.auth.apiKey — the bootstrap credential
Section titled “1. config.auth.apiKey — the bootstrap credential”The bootstrap superadmin key is usable with no database round-trip. It is always superadmin by
design and serves as the credential of last resort. Core can also read it from AUTH_API_KEY, but the chart writes it
into the rendered config file. That is why the chart renders the core config into a Secret
rather than a ConfigMap.
helm upgrade --install opentremor helm/opentremor \ --set config.auth.apiKey="$(openssl rand -base64 32)" \ ...If you leave it empty, the chart fails with an explanation instead of installing. Without an
api_key, OpenTremor resolves every request to the anonymous owner of the default org: a
multi-tenant system with its tenancy turned off. To accept that on purpose, for a throwaway
single-user cluster, set config.auth.disableAuthentication: true.
The task scheduler authenticates with this same value, read from the same Secret rather than a
copy that can drift — the endpoints it calls require is_superadmin, which an org-scoped service
account from POST /v1/auth/keys can never be.
2. The MongoDB URI
Section titled “2. The MongoDB URI”Never stored in a ConfigMap. In production, create the Secret out of band and point the chart at
it; the URI is injected as MONGODB_URI, which core’s config loader gives precedence over the
file:
kubectl create secret generic opentremor-mongo-secret \ --namespace opentremor \ --from-literal=mongodb-uri="mongodb://opentremor:<password>@mongo:27017/opentremor?authSource=opentremor"existingSecret: name: opentremor-mongo-secret key: mongodb-uriFor development, mongodb.enabled: true deploys a bundled instance and the URI is derived from
its Service — config.storage.mongodb.uri can stay empty. With neither, the chart fails to render
rather than starting a pod that cannot reach a database.
3. The signing and encryption keys
Section titled “3. The signing and encryption keys”JWT_SECRET, SECRETS_ENCRYPTION_KEY and TWO_FACTOR_SECRET_KEY are read from env vars, so they get
first-class plumbing through one Secret:
kubectl create secret generic opentremor-app-secrets \ --namespace opentremor \ --from-literal=jwt-secret="$(openssl rand -base64 32)" \ --from-literal=secrets-encryption-key="$(openssl rand -base64 32)" \ --from-literal=two-factor-secret-key="$(openssl rand -base64 32)"appSecrets: existingSecret: opentremor-app-secrets keys: jwtSecret: jwt-secret secretsEncryptionKey: secrets-encryption-key twoFactorSecretKey: two-factor-secret-key defaultAdminPassword: "" # optional — DEFAULT_ADMIN_PASSWORD4. Registry credentials
Section titled “4. Registry credentials”kubectl create secret docker-registry your-registry-pull-secret \ --namespace opentremor \ --docker-server=<your-registry> \ --docker-username=<username> \ --docker-password=<password-or-token>Password resets, email verification and invitations are written to the API’s log until you point the chart at an SMTP relay. The password goes in the same Secret as the keys above:
config: mail: backend: smtp smtp: host: smtp.example.com port: 587 username: apikeyappSecrets: existingSecret: opentremor-app-secrets keys: smtpPassword: smtp-passwordSee Email for what is sent and when.
Background jobs
Section titled “Background jobs”Every core replica runs a job worker, so scaling replicaCount scales job throughput too. A job
whose replica is lost mid-run goes back on the queue once its lease runs out:
config: worker: concurrency: 4 # jobs one replica runs at once leaseSeconds: 300 # how long a lost replica's jobs wait before another picks them upSee worker.
GitLab integration
Section titled “GitLab integration”Off by default. A platform admin turns it on in the dashboard (Platform Admin → Connections → GitLab) and sets which hosts it may reach. The chart does not set it.
The chart only carries an optional default CA:
config: gitlab: caBundleSecret: name: corp-ca # kubectl create secret generic corp-ca --from-file=ca.pem key: ca.pemEach org can paste its own company CA on its GitLab connection, so caBundleSecret is only a
default for orgs that give none. It is useful when they all sit behind the same CA. It is mounted
read-only at /etc/opentremor-gitlab-ca/ and passed as gitlab.ca_bundle. The server’s strict
TLS verification refuses a CA certificate without a keyUsage extension. See
gitlab and the GitLab integration. With
existingConfigSecret, write gitlab.ca_bundle into your own file; the CA mount still comes
from caBundleSecret.
Bringing your own config file
Section titled “Bringing your own config file”To keep the API key out of Helm’s hands entirely — SOPS, External Secrets, a Vault injector — render the whole core config yourself and point the chart at it. The chart then renders no config Secret of its own:
existingConfigSecret: name: opentremor-core-config key: config.yamlSet taskScheduler.existingApiKeySecret alongside it, so the scheduler still gets a credential.
What the chart can and cannot configure
Section titled “What the chart can and cannot configure”config: in values.yaml carries only the sections core reads from its config file:
deployment, storage, auth, cors, rateLimit, mail, worker, gitlab.
| Value | Default | Purpose |
|---|---|---|
config.deployment.mode | self_hosted | Leave it. cloud is for the operator’s own hosted offering and gates packs behind a plan — see deployment |
config.cors.enabled | false | Render a cors section. Off, core’s permissive default applies, which is fine when the API and dashboard share one ingress |
config.cors.allowOrigins / allowMethods / allowHeaders / allowCredentials | ["*"] / ["*"] / ["*"] / true | The cors section when enabled. A credentialed request can’t use *: list the dashboard’s real origin |
config.rateLimit.enabled | true | Brute-force protection on credential checks. The five thresholds are admin-editable under Platform Admin → Security → Rate Limits, not set here |
config.worker.pollSeconds / enabled | 2 / true | See Background jobs |
trustedProxies | [] | IPs or CIDRs of the proxies in front of core, usually the cluster’s pod CIDR. Core trusts X-Forwarded-For only for hops these proxies added. Leave it empty behind an ingress, and every caller gets the ingress controller’s address. API-key IP allowlists then stop matching. Rendered as TRUSTED_PROXIES |
networkAccess.verdict.dashboard / docs | false / false | Make the dashboard and docs pods ask core’s network access verdict before each page. Needs trustedProxies to cover those pods; the chart refuses to render without it. If core is down, those pages return 503 |
networkAccess.listSourcesConfigMap | "" | A ConfigMap of address list files, mounted at /etc/opentremor/network-lists for file lists. Empty disables file lists |
networkAccess.clusterDomain | cluster.local | The cluster’s DNS domain. The docs pod’s nginx resolves the API by its full name, <release>.<namespace>.svc.<domain>, because nginx applies no search domains |
Probes: startupProbe and livenessProbe call /health, which checks only the process, so a
MongoDB outage doesn’t restart healthy pods. readinessProbe calls /health/ready, which also
pings storage, so a pod that can’t reach the database stops receiving traffic.
Everything else you might expect to find there is managed live through the admin API and reset to
its hardcoded default at every boot, so a value in a config file — chart-rendered or not — is
silently discarded: logging, registration, branding, social_login, server, session,
retention, jobs, org_offboarding, the rate_limit thresholds, analysis, feedback, llm
and gitlab.egress. mcp and telemetry go further still: both are read once, synchronously,
inside create_app() before any stored override could reach them, so they are fixed for the life
of the process and not editable anywhere.
Set the live ones once the pod is up:
curl -X PATCH https://opentremor.example.com/v1/admin/settings \ -H "X-API-Key: <admin-key>" -H "Content-Type: application/json" \ -d '{"server_public_base_url": "https://opentremor.example.com"}'Set server_public_base_url. Report links, emailed links and the GitHub App manifest are built
only from it, never from the request’s Host or X-Forwarded-* headers. Without it, reports carry
no link and the manifest flow returns 501.
With the dashboard deployed, set server_dashboard_base_url too — invite links and the GitHub App
manifest redirect point at dashboard pages, and without it they silently drop the /dashboard
prefix:
-d '{"server_dashboard_base_url": "https://opentremor.example.com/dashboard"}'Ingress routing
Section titled “Ingress routing”Everything is served from one host, path-routed — same-origin, no separate subdomains, no extra
reverse-proxy layer. Each paths[] entry names its backend with service, which accepts three
shorthands (api, dashboard, docs) resolved to this release’s real Service names, so nothing
has to hardcode a release name. Any other value is used as a literal Service name. Omitting
service means api.
ingress: enabled: true className: nginx annotations: nginx.ingress.kubernetes.io/proxy-read-timeout: "3600" # SSE keep-alive hosts: - host: opentremor.example.com paths: - path: / pathType: Prefix - path: /dashboard pathType: Prefix service: dashboard - path: /docs pathType: Prefix service: docs tls: - secretName: opentremor-tls hosts: - opentremor.example.comRouting to a workload you haven’t enabled fails at render time rather than producing an Ingress that points at a Service which doesn’t exist.
Platform MCP
Section titled “Platform MCP”mcp.enabled: true runs the platform MCP. It reaches the API through the
release’s own Service and needs no secret: every MCP request carries the caller’s access token or
API key. Give it its own host, since the endpoint is at the service’s root:
mcp: enabled: trueingress: enabled: true hosts: - host: mcp.example.com paths: - path: / pathType: Prefix service: mcpA path on the API host (/platform-mcp, as the compose stacks do) needs your ingress controller to
strip the prefix.
For hosted clients that connect through OAuth (Claude.ai, ChatGPT), set both public URLs. The MCP service tells the client where to sign in:
mcp: publicUrl: https://mcp.example.com issuerUrl: https://api.example.comWorkloads
Section titled “Workloads”Dashboard
Section titled “Dashboard”dashboard: enabled: true basePath: /dashboard replicaCount: 1 image: repository: <your-registry>/opentremor-dashboard tag: "a1b2c3d" service: port: 3000Server-side (Server Component) fetches reach the API over the cluster network via API_BASE, which
the chart sets for you. Browser-side calls are same-origin and resolve through the ingress.
docs: enabled: true basePath: /docs image: repository: <your-registry>/opentremor-docs tag: "a1b2c3d"The docs image uses stock nginx, which needs to write its pid and cache and starts its master
process as root. The chart therefore gives docs its own docs.podSecurityContext and
docs.securityContext, separate from the API’s hardened settings.
That pair drops every capability and then adds exactly three back:
capabilities: drop: [ALL] add: [CHOWN, SETGID, SETUID]Without them the pod cannot start at all. nginx’s entrypoint chowns its cache directories before
the master forks, so with no CHOWN it exits 1 on nginx: [emerg] chown("/var/cache/nginx/ client_temp", 101) failed (1: Operation not permitted) and CrashLoopBackOffs; the master then
starts its workers as the unprivileged nginx user, which needs SETGID and SETUID. The other
capabilities stay dropped and allowPrivilegeEscalation stays false.
Rebuilding the image on nginxinc/nginx-unprivileged is what removes the need for all three, and
would let this go back to a bare drop: [ALL].
Task scheduler
Section titled “Task scheduler”taskScheduler: enabled: true image: repository: <your-registry>/opentremor-task-scheduler tag: "a1b2c3d" jobs: - name: retention_sweep method: POST path: /v1/admin/retention/run heartbeat_minutes: 15 - name: org_purge method: POST path: /v1/admin/organizations/purge-pending heartbeat_minutes: 60 - name: jobs_sweep method: POST path: /v1/admin/jobs/sweep heartbeat_minutes: 15 - name: knowledge_sync method: POST path: /v1/admin/knowledge/sync heartbeat_minutes: 60 - name: jira_sync method: POST path: /v1/admin/jira/sync heartbeat_minutes: 1 - name: audit_push_drain method: POST path: /v1/admin/audit-sinks/drain heartbeat_minutes: 1 - name: backup_tick method: POST path: /v1/admin/backups/tick heartbeat_minutes: 15The heartbeats are short on purpose. Core holds the real schedule and does nothing on a call
when no work is due. Adding a job as core grows more scheduled admin actions is
a values change, not a code change. core.base_url is derived from the release, and the credential
comes from the Secret core reads.
Single replica, strategy: Recreate — a second one would double every heartbeat for no benefit.
The Service is not routed through the ingress; reach its status endpoint directly:
kubectl --namespace opentremor port-forward svc/opentremor-task-scheduler 8080curl http://127.0.0.1:8080/jobsRotating config.auth.apiKey changes the Secret, but an env var sourced from a secretKeyRef does
not restart a running pod — follow a rotation with
kubectl rollout restart deployment/opentremor-task-scheduler.
Backups
Section titled “Backups”backup: recipients: - age1qyqszqgpqyqszqgpqyqszqgpqyqszqgpqyqszqgpqyqszqgpqyqs3d2hd scratchSizeLimit: 10Girecipients are the age public keys every backup is encrypted to, injected as
BACKUP_AGE_RECIPIENTS. Setting them pins the keys. Leave them empty to set the keys in
Platform Admin → System → Backups → Encryption key instead. Then turn backups on and choose the target
in Platform Admin → System → Backups → Schedule & storage. Use the s3 target on Kubernetes: each backup is written to an
emptyDir of scratchSizeLimit, uploaded, then removed. A local backup would be lost when the
pod is rescheduled. See Backups and Restore for the keys and the
restore procedure.
Bundled MongoDB
Section titled “Bundled MongoDB”mongodb: enabled: true persistence: enabled: true size: 8GiA single hand-written Deployment and Service — not a sub-chart — with no authentication, no replica
set, so helm install produces something that boots. Without
persistence.enabled, every restart of that pod loses the whole database. Use a real managed
MongoDB via existingSecret for anything else.
It runs mongo:7.0, not 8, and that is deliberate. Every MongoDB 8.x build refuses to start on
Linux 6.19 and newer, exiting immediately with MongoDB cannot start: Linux kernel versions 6.19 and newer has a known incompatibility with this version of MongoDB
(SERVER-121912). A container shares the host’s
kernel, so no image or securityContext works around it. On a current kernel the pod goes into
CrashLoopBackOff. If you point existingSecret at your own MongoDB, this constraint is yours to
check against the kernel your nodes run.
Initialise MongoDB indexes
Section titled “Initialise MongoDB indexes”Once the pod is up:
curl -X POST https://opentremor.example.com/v1/admin/storage/prepare-mongodb \ -H "X-API-Key: <admin-key>" -H "Content-Type: application/json" \ -d '{"uri": "mongodb://opentremor-mongodb:27017", "database": "opentremor"}'Core also creates its indexes at every start, so this is only needed for a database prepared ahead of time or a least-privilege app user. The UI shows this under Platform Admin → System → Database. It is idempotent and covers the full current collection/index set. See Platform Admin — Preparing MongoDB.
Scaling and availability
Section titled “Scaling and availability”replicaCount: 2
autoscaling: enabled: true minReplicas: 2 maxReplicas: 5 targetCPUUtilizationPercentage: 70 targetMemoryUtilizationPercentage: 75
podDisruptionBudget: enabled: true minAvailable: 1 # set this or maxUnavailable, never bothAny replica count above one requires appSecrets.existingSecret — see secret 3 above.
Upgrade
Section titled “Upgrade”Follow Upgrade and roll back: read the release’s upgrade notes, then run
helm upgrade with the new image tags. Core applies schema migrations at startup. One pod
migrates, and the others wait for it. The startupProbe allows 10 minutes for that
(failureThreshold: 120). Raise it for a large database, or the pod is killed mid-migration.
Metrics
Section titled “Metrics”Core exposes /metrics. With the Prometheus Operator CRDs installed, the chart can register a
ServiceMonitor pointing at it — the same series
OpenTremor Monitoring’s Grafana dashboard reads:
metrics: serviceMonitor: enabled: true interval: 30s labels: release: kube-prometheus-stack # match your Prometheus's serviceMonitorSelectorError reporting
Section titled “Error reporting”Off by default. Set a DSN to have the API, the task scheduler and the dashboard report errors to a Sentry-compatible server you run, such as GlitchTip:
errorReporting: dsn: "http://<key>@glitchtip.monitoring:8000/1" environment: production tracesSampleRate: "0.05" # the API only; the other services send no tracesThe chart sets SENTRY_DSN and SENTRY_ENVIRONMENT on all three workloads, and
SENTRY_TRACES_SAMPLE_RATE on the API. See Logs and Troubleshooting for details on what each service sends.
Resource limits and security contexts
Section titled “Resource limits and security contexts”resources: requests: { cpu: 100m, memory: 256Mi } limits: { cpu: 500m, memory: 512Mi }
podSecurityContext: runAsNonRoot: true runAsUser: 1000 fsGroup: 1000
securityContext: allowPrivilegeEscalation: false readOnlyRootFilesystem: true capabilities: drop: [ALL]The API and task-scheduler pods run with a read-only root filesystem, so HOME is pointed at
an emptyDir mounted on /tmp — the pod’s uid has no home of its own. The images ship
precompiled bytecode, so Python never needs to write .pyc files at start-up.
Published images
Section titled “Published images”Each workspace release pushes five images to ghcr.io/opentremor, tagged with the release
version without the leading v:
| Workload | Image |
|---|---|
| API (core with the thirteen first-party packs) | ghcr.io/opentremor/opentremor-core |
| Dashboard | ghcr.io/opentremor/opentremor-dashboard |
| Docs | ghcr.io/opentremor/opentremor-docs |
| Task scheduler | ghcr.io/opentremor/opentremor-task-scheduler |
| Platform MCP | ghcr.io/opentremor/opentremor-mcp |
Before pushing anything, the release job installs this chart into a kind cluster with these
images and all workloads enabled. The dashboard and docs images are built for /dashboard and /docs,
the chart’s default base paths.
The packages are private. Create a pull secret and list it in imagePullSecrets.
The published chart (oci://ghcr.io/opentremor/charts/opentremor) already names its release’s
images. A chart from a clone of OpenTremor-deployments carries that repo’s own version instead,
so set the tags to the release you install:
--set image.tag=1.2.0 \--set dashboard.image.tag=1.2.0 \--set docs.image.tag=1.2.0 \--set taskScheduler.image.tag=1.2.0 \--set mcp.image.tag=1.2.0CI/CD pipeline
Section titled “CI/CD pipeline”A typical pipeline builds and deploys on PR (dev) and merge to main (prod):
| Event | Trigger | Environment |
|---|---|---|
| PR opened / updated | pull_request → main | dev |
| Merge to main | push → main | prod |
Image tagging
Section titled “Image tagging”| Event | Tag format | Example |
|---|---|---|
| Pull request | pr-<number>-<sha7> | pr-42-a1b2c3d |
| Merge to main | <sha7> | a1b2c3d |
Five images are built, one per workload: core, dashboard, docs, task-scheduler, and mcp. The dashboard and docs images take the base-path build args described above, so a pipeline that serves them under a prefix must pass the same prefix at build time that the ingress routes at deploy time.
Required CI configuration
Section titled “Required CI configuration”Secrets (repo-level):
| Secret | Description |
|---|---|
REGISTRY_URL | Registry hostname, e.g. registry.company.com |
REGISTRY_USERNAME | Registry user |
REGISTRY_TOKEN | Registry password / token |
Variable (repo-level):
| Variable | Description |
|---|---|
AWS_REGION | AWS region, e.g. eu-west-1 |
GitHub Environments (Settings → Environments → New environment):
Create dev and prod. In each, add:
| Secret | Description |
|---|---|
AWS_ROLE_ARN | IAM role ARN (OIDC) |
EKS_CLUSTER_NAME | EKS cluster name |
OPENTREMOR_API_KEY | The bootstrap credential passed to --set config.auth.apiKey |
Add a required reviewer protection rule on prod to gate production deploys.
AWS OIDC setup
Section titled “AWS OIDC setup”Keyless authentication via GitHub OIDC. In your AWS account:
- Create an OIDC identity provider:
token.actions.githubusercontent.com - Create two IAM roles (one per environment) with this trust policy:
{ "Effect": "Allow", "Principal": { "Federated": "<oidc-provider-arn>" }, "Action": "sts:AssumeRoleWithWebIdentity", "Condition": { "StringLike": { "token.actions.githubusercontent.com:sub": "repo:<org>/opentremor-deployments:environment:<dev|prod>" } }}Each role needs eks:DescribeCluster and the permissions to run helm upgrade.
Environment overlays
Section titled “Environment overlays”values-dev.yaml and values-prod.yaml are complete environments. values-eks.yaml is an
additional layer — ALB ingress annotations, including the load-balancer idle timeout the MCP
endpoint’s SSE streams need — and is stacked on one of the other two, never used alone:
helm upgrade --install opentremor helm/opentremor \ -f helm/opentremor/values-dev.yaml \ -f helm/opentremor/values-eks.yaml \ --set config.auth.apiKey="$(cat ./api-key)" \ --namespace opentremor --create-namespaceManual deploy
Section titled “Manual deploy”helm upgrade --install opentremor \ helm/opentremor/ \ --namespace opentremor \ --create-namespace \ --set image.repository="<your-registry>/opentremor-core" \ --set image.tag="a1b2c3d" \ --set config.auth.apiKey="$(cat ./api-key)" \ --values helm/opentremor/values-prod.yaml \ --atomic \ --timeout 5mDry-run / diff
Section titled “Dry-run / diff”helm template opentremor helm/opentremor/ \ --values helm/opentremor/values-prod.yaml \ --set config.auth.apiKey=placeholder \ --namespace opentremor
helm diff upgrade opentremor helm/opentremor/ \ --values helm/opentremor/values-prod.yaml \ --namespace opentremorThe chart reports every misconfiguration it finds in one pass rather than one per run, so a failed
helm template lists everything that needs fixing.
Uninstall
Section titled “Uninstall”helm uninstall opentremor --namespace opentremor
# PVCs are not deleted automaticallykubectl delete pvc -l app.kubernetes.io/instance=opentremor -n opentremor