LumiBaseDocs

Kubernetes (Helm chart)

The official chart in deploy/helm/lumibase/ runs the published image ghcr.io/khuepm/lumibase-cms on Kubernetes: the CMS API and the Studio from one Deployment on one origin, migrations before the server starts, probes on the server's own health routes, and the hardening the image was built for (non-root UID 65532, read-only root filesystem, no capabilities). PostgreSQL and Redis are bundled for a first install and replaced by managed services for production; Meilisearch is optional.

ResourceWhen
Deployment <release>-lumibase (API + Studio, role all or web)always
Service, ConfigMap, Secret, ServiceAccountalways
StatefulSet + Service for PostgreSQL / Redispostgresql.enabled / redis.enabled (default on)
StatefulSet + Service for Meilisearchmeilisearch.enabled
Deployment <release>-lumibase-worker (role worker)worker.enabled
Job <release>-lumibase-migrate-<hash>migrations.mode=job
Ingress (TLS optional)ingress.enabled
HorizontalPodAutoscaler, PodDisruptionBudget, NetworkPolicyautoscaling.enabled, podDisruptionBudget.enabled, networkPolicy.enabled
helm test podtests.enabled (default on)

Requirements: Kubernetes 1.25 or newer, Helm 3.8 or newer (OCI registries), and a default StorageClass when the bundled services keep persistence on. The chart calls the image's distroless entrypoint and migration runner directly, so it needs the hardened image from Hardened image — the release the chart is published with, or image.tag=edge for main.

Install

The chart is published as an OCI artifact with every release, versioned like the release, and its default image tag is that same release:

bash
helm install lumibase oci://ghcr.io/khuepm/charts/lumibase --version <version> \
  --namespace lumibase --create-namespace \
  --set publicUrl=https://cms.example.com

From a checkout, use the path instead: helm install lumibase ./deploy/helm/lumibase ….

publicUrl is the one value you must give. In production the server refuses to start without CORS_ALLOWED_ORIGINS, and the chart fails the render with a message rather than leaving a pod in a crash loop. It accepts any one of: publicUrl, corsAllowedOrigins, or ingress.enabled with a host (the origin is then https://<host> when a TLS entry lists that host, http://<host> otherwise).

Try it locally (kind, port-forward)

bash
kind create cluster
helm install lumibase ./deploy/helm/lumibase -n lumibase --create-namespace \
  --set publicUrl=http://localhost:1989 --wait --timeout 10m
kubectl -n lumibase port-forward service/lumibase 1989:80

Then open http://localhost:1989/setup. The install notes print the next steps, including the setup-token command below.

Setup token

The chart sets LUMIBASE_REQUIRE_SETUP_TOKEN=true (setup.requireToken): the instance is reachable before anyone has set it up, and without the token whoever reaches /setup first would own it. The first web pod to start mints the token and prints it once:

bash
kubectl -n lumibase logs -l app.kubernetes.io/instance=lumibase,app.kubernetes.io/component=cms \
  --tail=-1 --prefix | grep SETUP_TOKEN=

The plaintext is not stored, so a pod restart does not print it again. If it is lost before setup is complete, clear the stored hash and restart; the next start prints a new token (the statement is CLEAR_SETUP_TOKEN_SQL in apps/cms/src/modules/setup/startup.ts):

bash
kubectl -n lumibase exec statefulset/lumibase-postgresql -- \
  psql -U lumibase -d lumibase -c "UPDATE lumibase_system_state SET setup_token_hash = NULL WHERE id = 'singleton';"
kubectl -n lumibase rollout restart deployment/lumibase

Secrets

The chart-managed Secret <release>-lumibase holds JWT_SECRET, ENCRYPTION_KEY and the passwords of the bundled services. For each value the order is: the value you set, else the value already in the Secret (read with Helm's lookup, so helm upgrade keeps it), else a newly generated one. Generated values are never written back to your values, so nothing secret ends up in a file you commit.

  • ENCRYPTION_KEY is generated as standard base64 of 32 random bytes, the form the server accepts. A key you set is checked at render time against the same rule (16, 24 or 32 bytes, canonical padding) — the server would refuse anything else in production.
  • The Secret carries helm.sh/resource-policy: keep (secrets.keepOnUninstall): helm uninstall leaves it in place, and a reinstall under the same release name and namespace reuses it instead of minting a key that cannot read the old data.
  • Back up ENCRYPTION_KEY right after the first install (the notes print the command). Encrypted fields and two-factor seeds cannot be read without it; see Encryption keys.
  • Bundled-service URLs are never stored: the pod spec carries postgresql://lumibase:$(LUMIBASE_HELM_POSTGRES_PASSWORD)@…, and Kubernetes fills in the password from the Secret when the container starts.

GitOps (Argo CD, Flux) and helm template: lookup returns nothing when the chart is rendered without a cluster connection, so generated values would change on every sync — a new ENCRYPTION_KEY each time. Create the Secret yourself and point the chart at it:

bash
kubectl -n lumibase create secret generic lumibase-app \
  --from-literal=JWT_SECRET="$(openssl rand -base64 48)" \
  --from-literal=ENCRYPTION_KEY="$(openssl rand -base64 32)"
yaml
secrets:
  existingSecret: lumibase-app   # keys JWT_SECRET and ENCRYPTION_KEY

The same applies to the bundled passwords (postgresql.auth.existingSecret, redis.auth.existingSecret), or run PostgreSQL and Redis outside the chart.

Production values

yaml
publicUrl: https://cms.example.com
secrets:
  existingSecret: lumibase-app
ingress:
  enabled: true
  className: nginx
  hosts:
    - host: cms.example.com
      paths: [{ path: /, pathType: Prefix }]
  tls:
    - secretName: cms-example-com-tls
      hosts: [cms.example.com]
postgresql:
  enabled: false
database:
  external:
    existingSecret: lumibase-db        # key DATABASE_URL, with sslmode=require
redis:
  enabled: false
  external:
    existingSecret: lumibase-redis     # key REDIS_URL
meilisearch:
  external:
    host: https://search.example.com
    existingSecret: lumibase-search    # key MEILISEARCH_API_KEY
s3:
  endpoint: https://s3.eu-central-1.amazonaws.com
  bucket: lumibase-media
  existingSecret: lumibase-s3          # keys S3_ACCESS_KEY, S3_SECRET_KEY
podDisruptionBudget:
  enabled: true
networkPolicy:
  enabled: true
  ingressFrom:
    - namespaceSelector:
        matchLabels:
          kubernetes.io/metadata.name: ingress-nginx

Values and the variables they set

Every setting maps to a variable the image reads; see Environment variables for what each one does. Anything else goes in config (non-secret, rendered into the ConfigMap, and it wins over the chart's own keys), extraEnv or extraEnvFrom.

ValueVariable
environmentNODE_ENV (when production), LUMIBASE_ENV
publicUrl (or the ingress host)LUMIBASE_PUBLIC_URL
corsAllowedOrigins (default: the public origin)CORS_ALLOWED_ORIGINS
setup.requireTokenLUMIBASE_REQUIRE_SETUP_TOKEN
studio.enabledLUMIBASE_SERVE_STUDIO
secrets.*JWT_SECRET, ENCRYPTION_KEY
postgresql.* / database.external.*DATABASE_URL
database.sslMode (disable with the bundled PostgreSQL)DATABASE_SSL_MODE
database.rls, database.systemUrl.*LUMIBASE_DB_RLS, DATABASE_SYSTEM_URL
redis.*REDIS_URL
meilisearch.*MEILISEARCH_HOST, MEILISEARCH_API_KEY
s3.*S3_ENDPOINT, S3_BUCKET, S3_ACCESS_KEY, S3_SECRET_KEY
cms.role, worker.enabledLUMIBASE_PROCESS_ROLE
worker.healthPortLUMIBASE_WORKER_HEALTH_PORT
migrations.modeSKIP_MIGRATIONS, MIGRATION_MODE (init container)
migrations.targetMIGRATE_TARGET (migration runners and gates)

The chart always sets LUMIBASE_RUNTIME=docker and PORT=1989. values.schema.json rejects malformed values before anything is rendered.

Migrations

Two pieces of the image's migration runner (dist/migrate.cjs) sequence every mode:

  • Lock. migrate.cjs apply holds a session-level PostgreSQL advisory lock for the whole apply. The key is fixed: 5509430018010346341, the ASCII bytes of LumiBase (pg_locks shows it as classid = 1282764137, objid = 1113682789). Runners that start together (several web replicas, a surge pod, an HPA scale-out, the entrypoint on two replicas) queue on it: the first applies, each later one then finds nothing pending, logs Nothing to apply, and exits 0. Postgres releases the lock when the runner's connection closes, so a killed pod never leaves it behind. A runner waits up to MIGRATION_LOCK_TIMEOUT seconds (default 900) and then fails, and Kubernetes retries it.
  • Gate. migrate.cjs wait --timeout <seconds> is read-only: it exits 0 once the database has no migration pending for the journal bundled in the image, polling with backoff (1 s doubling to 10 s), and exits 1 at the timeout (migrations.waitTimeoutSeconds, default 600), after which Kubernetes restarts the init container.

migrations.mode picks who applies them:

  • initContainer (default): each web pod first runs the image entrypoint with MIGRATION_MODE=preflight — which waits for the database with the entrypoint's own retry and backoff and prints the schema version — then node /app/dist/migrate.cjs apply under the lock. The server container starts with SKIP_MIGRATIONS=true. A failed migration keeps the pod out of service instead of serving on a half-migrated schema, and the rolling update stops there.
  • job: one Job, <release>-lumibase-migrate-<hash>, runs the same preflight and apply; web pods run only the gate. The hash is taken from the Job's pod spec, which Kubernetes does not let you change: a new image or database setting creates a new Job (Helm deletes the previous one), and re-applying unchanged values — helm upgrade, or an Argo CD sync of helm template output — leaves the finished Job alone. With networkPolicy.enabled the bundled services also admit the Job's pods.
  • entrypoint: no init containers on web pods; the image migrates on every start under the same lock, as on Docker and the one-click platforms.
  • none: SKIP_MIGRATIONS=true everywhere and no gate; run migrations from your own pipeline before rolling out.

Worker pods never migrate. In every mode but none, the worker Deployment starts with a migrations-ready init container that runs the gate, with the same image and hardening as the web migrator, so queue consumers and the scheduler do not start on an older schema than the one their image was built for, on a fresh install or on an upgrade.

Not a Helm hook on purpose: a pre-install or pre-upgrade hook runs before the bundled PostgreSQL and the chart's Secret exist, so on a first install it could not reach the database; a post-install hook under helm install --wait would wait for web pods that are themselves waiting for the migration. Hooks are also not release resources, so a rollback would not track them.

migrations.target (advanced) stops the history at one migration tag, for example 0029_activation_milestones, for runners and gates alike. It exists for staged upgrades and for the CI upgrade test; leave it empty.

Upgrades with several replicas

On helm upgrade to an image with new migrations, with initContainer mode:

  1. New web pods start (as many at once as cms.strategy allows; an HPA may add more). Each runs its migrator; the lock lets exactly one apply, the others wait for it and find nothing to apply.
  2. The new worker pod's gate sees the pending migrations and waits; its worker container starts only after the apply has committed.
  3. Old web and worker pods keep serving until their replacements are Ready, so for the length of the rollout old code runs against the new schema. Keep migrations backward-compatible with the previous release (expand, then contract one release later), as the bundled ones are.

A failed migration rolls back its transaction, releases the lock and keeps the new pods in Init: the rollout stops, and the old pods keep serving.

Read Upgrades before moving image.tag across a major release.

Health checks

ProbePathWhy
startup, liveness/healthAnswers 200 whenever the process serves HTTP, so a database outage does not restart every pod.
readiness/health/ready or /health/health/ready answers 503 while any of database, cache, search, storage or queue is unhealthy.

cms.readinessPath empty (the default) picks /health/ready only when search and object storage are configured; otherwise /health, because /health/ready would report the missing service and never turn ready. Set it explicitly to override. Worker pods probe /health and /health/ready on worker.healthPort.

Scaling

  • cms.replicaCount or autoscaling.enabled (CPU, optionally memory) scale the web Deployment. Scheduled jobs are leader-locked through Redis, so more than one replica does not run them twice.
  • worker.enabled moves queue workers and the scheduler into their own Deployment (LUMIBASE_PROCESS_ROLE=worker), and the web pods switch to web.
  • Realtime limitation: on the Docker runtime WebSocket events are delivered in-process (packages/runtime/src/adapters/docker/realtime.ts), so with more than one web replica a client receives only the events published by the pod it is connected to. Keep one web replica if you depend on realtime, or accept that limitation.
  • podDisruptionBudget.enabled protects the web pods during node drains.

Bundled services

PostgreSQL (postgres:16-alpine), Redis (redis:7-alpine) and Meilisearch (getmeili/meilisearch:v1.7, the versions in docker/docker-compose.yml) are plain single-instance StatefulSets, non-root with a read-only root filesystem. They are not dependency subcharts: a subchart must be fetched from a chart repository at install time and pins its own release cadence and images, while a template in this chart installs offline and is reviewed with it. They have no replication and no backups; use them to evaluate, and use managed services in production. Redis runs with AOF persistence and noeviction, because BullMQ jobs must never be evicted.

Object storage is not bundled. Without s3.endpoint the instance boots and setup completes, but uploads do not work.

NetworkPolicy

With networkPolicy.enabled the web pods accept traffic only on their HTTP port (from networkPolicy.ingressFrom when set), the worker accepts none (traffic from the pod's own node, which carries the kubelet probes, is always allowed), and the bundled PostgreSQL, Redis and Meilisearch accept only the release's web and worker pods (and the migration Job's pods in migrations.mode=job). Egress is not restricted: the CMS calls object storage, LLM providers and webhooks.

Verify

bash
helm test lumibase -n lumibase --logs

The test pod uses the release image's own Node to check, through the Service, that /health answers, that /api/v1/setup/state answers, and that /setup serves the Studio shell. In CI, .github/workflows/helm.yml lints the chart, runs scripts/__tests__/helm-chart.test.mjs (render tests), and scripts/helm-kind-smoke.sh installs the chart on kind with the image built from the same commit, runs helm test, upgrades, and checks that ENCRYPTION_KEY did not change. It then installs a worker and two web replicas one migration short of the image's journal and upgrades them to the full journal, checking that the migrations table holds each migration exactly once, that exactly one web pod applied it, and that the worker started only after its gate passed; finally it switches the release to migrations.mode=job.

Upgrade and uninstall

bash
helm upgrade lumibase oci://ghcr.io/khuepm/charts/lumibase --version <new> -n lumibase -f my-values.yaml
helm uninstall lumibase -n lumibase

helm uninstall keeps the Secret (see Secrets) and the StatefulSets' PersistentVolumeClaims; delete them yourself when the data should go.

Last modified: 15/11/2026