Skip to content

Kubernetes (Helm)

Trimus ships a Helm chart (deploy/helm/trimus) and multi-arch container images on GHCR (ghcr.io/trimus-ai/trimus-{server,worker,seed}), published on each release (#134).

Quick start

helm install trimus ./deploy/helm/trimus \
  --set secrets.encryptionKey=$(openssl rand -base64 32)

kubectl port-forward svc/trimus-trimus 3100:3100   # then http://localhost:3100/

This brings up one all-role pod plus an in-cluster pgvector Postgres. Migrations run automatically on boot (advisory-locked, so it's safe even when the web tier scales).

The 3-role model (TRIMUS_ROLE)

One image, three roles — set per process. all (the default) preserves the single-process binary exactly.

Role Serves HTTP Runs background singletons Scale
all (default) ✅ ✅ 1 (holds a PVC)
web ✅ — N (stateless)
scheduler — ✅ 1 (no leader election yet)
worker (trimus-worker, separate binary) — claims tasks N

The background singletons (heartbeat dispatch, backup + backup-verify crons, GEPA evaluator, retention workers, …) run only under all/scheduler. Running N web replicas therefore never duplicates that work.

Switch the chart with deployment.mode:

helm upgrade trimus ./deploy/helm/trimus \
  --set deployment.mode=split \
  --set web.autoscaling.enabled=true \
  --set worker.enabled=true \
  --set projectFiles.backend=object_storage \
  --set projectFiles.s3.bucket=... --set projectFiles.s3.endpoint=... \
  --set projectFiles.s3.accessKeyId=... --set projectFiles.s3.secretAccessKey=...

v1 constraints

  • Scheduler = 1 replica. The chart refuses to render scheduler.replicas > 1.
  • Split-mode live (SSE) events cross tiers automatically (#237) — the scheduler NOTIFYs each live event on a Postgres channel and every web pod LISTENs and re-broadcasts it to its browsers. No extra infrastructure or config; all mode is single-process and unaffected.
  • Split mode needs object_storage project files — web/worker pods can't share the scheduler's ReadWriteOnce volume. The chart provisions an in-cluster MinIO by default (#236); or point at any external S3-compatible endpoint.

External Postgres (managed) and S3

  • Postgres — --set postgres.enabled=false --set postgres.external.url=postgres://…. The managed DB must have the pgvector extension (migrations create the vector type); stock Postgres fails. See database.md.
  • Object storage — set projectFiles.backend=object_storage + projectFiles.s3.*. See project-files-object-storage.md.

Reference

The chart's README and commented values.yaml are the full values reference. TRIMUS_ROLE and the other env vars are in environment.md.