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
235 lines
8.2 KiB
Markdown
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)
|