# Gramps Web Helm chart

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

```sh
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:

```yaml
postgresql:
  enabled: true
valkey:
  enabled: true
```

For external services:

```yaml
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:

```yaml
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:

```yaml
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:

```yaml
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:

```sh
./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`](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:

```sh
./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. The chart workflow
validates the chart, publishes it to
`registry.brunner.ninja/feedc0de/charts/gramps-web`, and deploys that exact
package to the `gramps` namespace. The registry credentials are used by CI for
publishing and reading the OCI chart; the public PostgreSQL image needs no
Kubernetes image-pull Secret. Before publishing the chart, a trusted host job
checks that the configured PostgreSQL image exists and builds it once with
native Podman if the repository is still empty. Ordinary chart changes
therefore do not rebuild PostgreSQL.

The ordered main workflow also rebuilds the image when `postgresql-image/`
changes. A separate refresh workflow runs when manually dispatched and on a
weekly schedule so the moving Bitnami PostgreSQL 18 base receives updates. It
uses native Podman on the host runner and publishes
`registry.brunner.ninja/feedc0de/postgres-with-locales:18-locales`.
Generating each locale is time-bounded, and the job itself has a 20-minute
timeout so a broken upstream image cannot occupy the runner indefinitely.

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

```sh
./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:

- [Gramps Web configuration](https://github.com/gramps-project/gramps-web-docs/blob/main/docs/en/install_setup/configuration.md)
- [Gramps Web OIDC configuration](https://github.com/gramps-project/gramps-web-docs/blob/main/docs/en/install_setup/oidc.md)
- [Gramps Web PostgreSQL and locale guidance](https://github.com/gramps-project/gramps-web-docs/blob/main/docs/en/install_setup/postgres.md)
- [Bitnami PostgreSQL chart](https://github.com/bitnami/charts/tree/main/bitnami/postgresql)
- [Bitnami Valkey chart](https://github.com/bitnami/charts/tree/main/bitnami/valkey)