Skip to content
DashboardWebsite

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:

WorkloadValues flagWhat it is
corealways onThe API — Deployment, Service, config Secret, ServiceAccount, optional Ingress/HPA/PDB/PVC
dashboarddashboard.enabledThe Next.js UI, on its own Deployment+Service
docsdocs.enabledThis documentation site, served as static files by nginx
task-schedulertaskScheduler.enabledThe “cron” core doesn’t have — see Task Scheduler
mcpmcp.enabledThe platform MCP: lets an agent manage OpenTremor as its user. Stateless, holds no credential
mongodbmongodb.enabledA 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.


  • Kubernetes 1.26+
  • Helm 3.12+
  • A reachable MongoDB instance (in-cluster or external)

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.

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

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.

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

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

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:

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

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

JWT_SECRET, SECRETS_ENCRYPTION_KEY and TWO_FACTOR_SECRET_KEY are read from env vars, so they get first-class plumbing through one Secret:

Terminal window
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_PASSWORD
Terminal window
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
fromAddress: "OpenTremor <[email protected]>"
smtp:
host: smtp.example.com
port: 587
username: apikey
appSecrets:
existingSecret: opentremor-app-secrets
keys:
smtpPassword: smtp-password

See Email for what is sent and when.

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 up

See worker.

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

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

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

Set taskScheduler.existingApiKeySecret alongside it, so the scheduler still gets a credential.


config: in values.yaml carries only the sections core reads from its config file: deployment, storage, auth, cors, rateLimit, mail, worker, gitlab.

ValueDefaultPurpose
config.deployment.modeself_hostedLeave it. cloud is for the operator’s own hosted offering and gates packs behind a plan — see deployment
config.cors.enabledfalseRender 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["*"] / ["*"] / ["*"] / trueThe cors section when enabled. A credentialed request can’t use *: list the dashboard’s real origin
config.rateLimit.enabledtrueBrute-force protection on credential checks. The five thresholds are admin-editable under Platform Admin → Security → Rate Limits, not set here
config.worker.pollSeconds / enabled2 / trueSee 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 / docsfalse / falseMake 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.clusterDomaincluster.localThe 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:

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

Terminal window
-d '{"server_dashboard_base_url": "https://opentremor.example.com/dashboard"}'

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

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


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: true
ingress:
enabled: true
hosts:
- host: mcp.example.com
paths:
- path: /
pathType: Prefix
service: mcp

A 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.com
dashboard:
enabled: true
basePath: /dashboard
replicaCount: 1
image:
repository: <your-registry>/opentremor-dashboard
tag: "a1b2c3d"
service:
port: 3000

Server-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].

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: 15

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

Terminal window
kubectl --namespace opentremor port-forward svc/opentremor-task-scheduler 8080
curl http://127.0.0.1:8080/jobs

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

backup:
recipients:
- age1qyqszqgpqyqszqgpqyqszqgpqyqszqgpqyqszqgpqyqszqgpqyqs3d2hd
scratchSizeLimit: 10Gi

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

mongodb:
enabled: true
persistence:
enabled: true
size: 8Gi

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


Once the pod is up:

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


replicaCount: 2
autoscaling:
enabled: true
minReplicas: 2
maxReplicas: 5
targetCPUUtilizationPercentage: 70
targetMemoryUtilizationPercentage: 75
podDisruptionBudget:
enabled: true
minAvailable: 1 # set this or maxUnavailable, never both

Any replica count above one requires appSecrets.existingSecret — see secret 3 above.

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.


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 serviceMonitorSelector

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 traces

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


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.


Each workspace release pushes five images to ghcr.io/opentremor, tagged with the release version without the leading v:

WorkloadImage
API (core with the thirteen first-party packs)ghcr.io/opentremor/opentremor-core
Dashboardghcr.io/opentremor/opentremor-dashboard
Docsghcr.io/opentremor/opentremor-docs
Task schedulerghcr.io/opentremor/opentremor-task-scheduler
Platform MCPghcr.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:

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

A typical pipeline builds and deploys on PR (dev) and merge to main (prod):

EventTriggerEnvironment
PR opened / updatedpull_request → maindev
Merge to mainpush → mainprod
EventTag formatExample
Pull requestpr-<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.

Secrets (repo-level):

SecretDescription
REGISTRY_URLRegistry hostname, e.g. registry.company.com
REGISTRY_USERNAMERegistry user
REGISTRY_TOKENRegistry password / token

Variable (repo-level):

VariableDescription
AWS_REGIONAWS region, e.g. eu-west-1

GitHub Environments (Settings → Environments → New environment):

Create dev and prod. In each, add:

SecretDescription
AWS_ROLE_ARNIAM role ARN (OIDC)
EKS_CLUSTER_NAMEEKS cluster name
OPENTREMOR_API_KEYThe bootstrap credential passed to --set config.auth.apiKey

Add a required reviewer protection rule on prod to gate production deploys.

Keyless authentication via GitHub OIDC. In your AWS account:

  1. Create an OIDC identity provider: token.actions.githubusercontent.com
  2. 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.


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:

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

Terminal window
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 5m

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

The chart reports every misconfiguration it finds in one pass rather than one per run, so a failed helm template lists everything that needs fixing.


Terminal window
helm uninstall opentremor --namespace opentremor
# PVCs are not deleted automatically
kubectl delete pvc -l app.kubernetes.io/instance=opentremor -n opentremor