This repository packages Gramps Web as a reusable Helm chart. PostgreSQL and Valkey are enabled by default through the Bitnami subcharts, but either service can be disabled and replaced independently. OIDC, S3 media storage, SMTP, workers, persistence, ingress, images, resources, and scheduling are optional or configurable.

Quick start

helm install family oci://registry.brunner.ninja/feedc0de/charts/gramps-web \
  --namespace gramps-web --create-namespace

The default installation creates random PostgreSQL, Valkey, and application secrets. Helm and the subcharts preserve those values across normal upgrades. Do not use --set ...password=... in production: command history and Helm release values can retain it. Create a Secret and use an existingSecret setting instead.

Data service choices

Bundled PostgreSQL and Valkey are independent:

postgresql:
  enabled: true
valkey:
  enabled: true

For external services:

postgresql:
  enabled: false
database:
  host: postgres.database.svc
  port: 5432
  username: gramps
  auth:
    existingSecret: gramps-database
    existingSecretKey: password

valkey:
  enabled: false
cache:
  host: valkey.cache.svc
  port: 6379
  auth:
    existingSecret: gramps-valkey
    existingSecretKey: valkey-password

The bundled charts remain fully configurable under postgresql.* and valkey.*. For example, a locale-capable PostgreSQL image can be selected without changing this chart:

global:
  security:
    allowInsecureImages: true
postgresql:
  image:
    registry: registry.example.com
    repository: platform/postgres-with-locales
    tag: 18-locales

Locales are supplied by the container image, not generated by Helm. The included arschrock image recipe generates de_AT.UTF-8, de_DE.UTF-8, en_GB.UTF-8, and en_US.UTF-8; its LOCALES build argument can be extended for other browser locales.

PostgreSQL chart upgrades update Kubernetes resources and the image. They do not convert a data directory between PostgreSQL major versions. Stay on the same PostgreSQL major for routine upgrades; use pg_upgrade or dump/restore for a major upgrade.

OIDC / Authentik

OIDC is off by default. A provider such as Authentik can be enabled with:

oidc:
  enabled: true
  issuer: https://auth.example.com/application/o/gramps/
  clientId: gramps-web
  clientSecret:
    existingSecret: gramps-oidc
    existingSecretKey: client-secret
  name: Company login
  disableLocalAuth: true
  autoRedirect: true
  groups:
    admin: Gramps Admins
    editor: Gramps Editors

Keep local authentication enabled until OIDC login and role mapping have been tested. Gramps supports custom OIDC providers, including Authentik, and can map OIDC groups to its roles.

Replicas

replicaCount and worker.replicaCount are configurable. Multiple web pods should only be attempted when tree data, user data, the search index, media, cache/broker, and application secret are all shared. The safer first scaling step is setting GUNICORN_NUM_WORKERS through config.extraEnv; upstream documents multiple Gunicorn workers, while it does not document Kubernetes web replicas as a supported topology. The chart therefore defaults to one web pod.

Health checks and metrics

Gramps Web exposes /ready, but upstream currently implements it as a shallow HTTP response rather than a dependency check. The chart therefore uses:

/ready for startup and liveness, so a temporary dependency outage does not create a web-pod restart loop;
a deep web readiness probe that checks /ready, runs an authenticated PostgreSQL SELECT 1, and performs an authenticated Valkey PING;
a targeted Celery self-ping for worker startup, readiness, and liveness;
the PostgreSQL and Valkey subcharts' native startup, readiness, and liveness probes.

The probe blocks traffic when the core API/database/cache path is broken, but it deliberately does not make pod health depend on Authentik, SMTP, or S3. Those should be monitored with external synthetic checks.

Gramps Web does not currently expose Prometheus application metrics. The bundled data-service charts do have optional exporters and ServiceMonitors:

postgresql:
  metrics:
    enabled: true
    serviceMonitor:
      enabled: true
valkey:
  metrics:
    enabled: true
    serviceMonitor:
      enabled: true

They remain disabled by default to avoid imposing exporter CPU/memory requests or Prometheus Operator CRDs on chart users.

Persistence and upgrades

The application PVC has a helm.sh/resource-policy: keep annotation by default. PostgreSQL and Valkey persistence are controlled by their subchart values. Back up PostgreSQL before any image or chart upgrade:

./backup.sh

The application image defaults to ghcr.io/gramps-project/grampsweb:latest with imagePullPolicy: Always. Set image.tag to a release tag if you prefer reproducible rollouts.

arschrock deployment

values-arschrock.yaml contains only non-secret cluster configuration. Existing credentials are moved by bootstrap-secrets.sh into gramps-runtime, gramps-postgresql, and gramps-valkey; none is rendered or committed.

Initial migration:

./backup.sh
./bootstrap-secrets.sh
./preflight.sh
kubectl apply -f ci-deployer.yaml
./create-ci-kubeconfig.sh   # save its output as Gitea KUBE_CONFIG_BASE64

Also configure QUAY_USERNAME and QUAY_TOKEN in Gitea. CI validates the chart, builds and tests the locale-enabled PostgreSQL 18 image, publishes the OCI chart to registry.brunner.ninja/feedc0de/charts/gramps-web, and deploys that exact chart package to the gramps namespace from the registry.

This deployment stores Helm release metadata in ConfigMaps. The CI identity cannot list Secrets or read gramps-runtime (OIDC, S3, database URIs, and app key). Bitnami's templates require direct lookup access to their configured password Secrets, so CI can read only gramps-postgresql, gramps-valkey, and the legacy postgresql Secret that its create-or-reuse helper checks.

The initial Helm deployment uses --take-ownership and preserves the existing StatefulSet/PVC names. Old postgresql and valkey Helm release records must only be removed after the new gramps release is healthy; never run helm uninstall postgresql or helm uninstall valkey after adoption because their historical manifests describe the live resources.

Automatic Helm rollback is intentionally disabled for the first ownership transfer because an install rollback could delete adopted resources. It is enabled automatically for every later upgrade.

Development

./test.sh
./render.sh

Chart.lock records the last-tested dependency packages. Chart.yaml uses compatible major-version ranges, and CI runs helm dependency update when it packages a release. This allows current subchart releases while avoiding an unreviewed breaking subchart-major jump.

Upstream references: