Files
feedc0de 706d40ca97
Validate, publish and deploy Gramps Web / validate (push) Successful in 23s
Validate, publish and deploy Gramps Web / ensure-postgresql-image (push) Successful in 37s
Validate, publish and deploy Gramps Web / publish (push) Successful in 18s
Validate, publish and deploy Gramps Web / deploy (push) Failing after 21s
Cleanups and CI improvements
2026-10-04 17:18:39 +02:00

235 lines
8.2 KiB
Markdown

# 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)