Skip to main content

Install with Helm

The official chart installs the Norn API, web dashboard, worker, database migrations, and authorisation policy seed. By default, it also installs single-node PostgreSQL, Valkey, and Garage.

Requirements​

  • Kubernetes 1.34 or newer
  • Helm 3 or 4
  • an Ingress controller and TLS certificate, unless routing is managed separately
  • persistent storage for each bundled data service
  • two DNS names: one for Norn and one for object storage

The bundled data services are suitable for evaluation and small installations. For production, use managed or highly available PostgreSQL, Valkey, and S3-compatible storage. The application workloads are the same in either configuration.

Configure the release​

Create a values file. This is the minimum configuration for an installation using the bundled data services:

values.yaml
ingress:
  className: nginx
  host: norn.example.com
  annotations:
    cert-manager.io/cluster-issuer: letsencrypt

postgresql:
  persistence:
    storageClass: fast-retained
    size: 20Gi

valkey:
  persistence:
    storageClass: fast-retained
    size: 4Gi

garage:
  persistence:
    storageClass: bulk-retained
    size: 50Gi

Point norn.example.com and storage.norn.example.com at the Ingress. The storage hostname defaults to storage.<ingress.host>; set garage.publicHost to use another name. The TLS certificate must cover both names.

The chart generates its own application, database, Valkey, and Garage credentials. They are retained on uninstall and reused on upgrade. For production, use an existing Secret or external secret controller as described in Helm secrets.

Install​

helm install norn oci://ghcr.io/usenorn/charts/norn \
  --namespace norn \
  --create-namespace \
  --values values.yaml \
  --wait \
  --timeout 15m

Without --version, Helm installs the newest published chart. Pin it with --version <chart-version> to install a specific one; the available versions are the Norn releases.

During installation, the chart waits for the data services, applies embedded database migrations, seeds the authorisation policy, and then starts Norn. The API and web workloads default to two replicas. The worker runs exactly one replica.

Verify and open Norn​

helm status norn --namespace norn
helm test norn --namespace norn --logs

Open https://norn.example.com and create the first account. If the instance is invite-only, close signups after bootstrap:

values.yaml
norn:
  configEnv:
    NORN_INSTANCE_SIGNUPS_OPEN: "false"

Apply the change using the upgrade procedure.

Production checklist​

Before adding users, confirm that you have:

  • external or backed-up PostgreSQL and object storage
  • Valkey configured with noeviction
  • an offline recovery copy of NORN_SECURITY_ENCRYPTION_KEY
  • SMTP configured and account recovery tested
  • unbuffered SSE routing for /v1/workspaces/<workspace>/events
  • a tested upgrade and restore procedure

Continue with the shared Norn configuration, then review the Helm-specific settings and operations.