feat: ship the admin docs as a zip on every release

doc/admin/{en,nl}/01-installation-helm.md describe how the chart works, laid
out like the player repo's doc/. ci/build-docs.sh fills the empty
VALUES:BEGIN/END markers with a table generated from values.yaml and packages
ister-chart-docs-<version>.zip, which release.yml now attaches to the GitHub
Release; ci.yml builds it on every PR so a broken marker fails there instead.
doc/ is .helmignore'd and doc/** now triggers a release.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>

Author: tijder

.github/workflows/ci.yml

@@ -67,6 +67,11 @@ jobs:
         with:
           args: -strict -summary -ignore-missing-schemas kubeconform-manifests.yaml
 
+      # Catches a broken VALUES marker or values.yaml drift on the PR instead of
+      # letting it fail the release build.
+      - name: Build the docs zip
+        run: ./ci/build-docs.sh 0.0.0-ci
+
   e2e:
     name: End-to-end on kind
     runs-on: ubuntu-latest

.github/workflows/release.yml

@@ -12,6 +12,8 @@ on:
       - values.yaml
       - values.schema.json
       - templates/**
+      # The docs ship as a zip on every release, so a doc change must release too.
+      - doc/**
   workflow_dispatch:
     inputs:
       bump:
@@ -104,6 +106,11 @@ jobs:
       - name: Generate release notes
         run: ./ci/release-notes.sh "${{ steps.version.outputs.version }}" "${{ steps.version.outputs.prev }}"
 
+      # doc/ with the values reference filled in from values.yaml; attached to the
+      # release below, mirroring the player repo's docs zip.
+      - name: Build the docs zip
+        run: ./ci/build-docs.sh "${{ steps.version.outputs.version }}"
+
       - name: Package
         run: |
           helm dependency build
@@ -133,6 +140,6 @@ jobs:
           git tag -a "v${VERSION}" -m "v${VERSION}"
           git push origin HEAD:main --follow-tags
 
-          gh release create "v${VERSION}" "ister-${VERSION}.tgz" \
+          gh release create "v${VERSION}" "ister-${VERSION}.tgz" "ister-chart-docs-${VERSION}.zip" \
             --title "v${VERSION}" \
             --notes-file RELEASE_NOTES.md

.gitignore

@@ -13,5 +13,8 @@ charts/
 *.tgz
 RELEASE_NOTES.md
 
+# Built by ci/build-docs.sh; attached to the GitHub Release, never committed.
+ister-chart-docs-*.zip
+
 # Rendered manifests the CI kubeconform step feeds to the container.
 kubeconform-manifests.yaml

.helmignore

@@ -16,3 +16,7 @@ values-production.yaml
 # CI scaffolding is not part of the chart.
 .github/
 ci/
+
+# Documentation ships as a release-asset zip (ci/build-docs.sh), not inside the chart.
+doc/
+ister-chart-docs-*.zip

CLAUDE.md

@@ -19,6 +19,7 @@ helm template ister . -f ci/values-ci.yaml             # values.schema.json is e
 helm package .
 
 ci/release-notes.sh 0.3.0 v0.2.0 && cat RELEASE_NOTES.md   # release notes, runs locally
+ci/build-docs.sh 0.0.0-local                               # the docs zip, runs locally
 ```
 
 There are four value profiles and CI renders all of them; a change to `values.yaml` or a template
@@ -96,6 +97,12 @@ Automatic, and the details matter before you touch `Chart.yaml`:
   of truth. `ci/release-notes.sh` mirrors that fallback so the migrations row is never blank.
 - Renovate (`renovate.json`), not Dependabot — Dependabot's docker manager cannot tell two images
   in one `values.yaml` apart when they share a tag string (dependabot-core#6891).
+- Every release also ships `ister-chart-docs-<version>.zip`, built by `ci/build-docs.sh` from
+  `doc/admin/{en,nl}/` (the player repo's `doc/` layout). The values reference in each chapter is
+  an **empty `VALUES:BEGIN`/`VALUES:END` marker pair in git** that the script fills from
+  `values.yaml` at build time — never commit content between the markers, and never spell the
+  literal markers out anywhere else in `doc/` (the script fills every pair it finds). `doc/` is
+  `.helmignore`d, so it never ends up in the chart tgz; a `doc/**` change does trigger a release.
 
 `server` and `player` publish semver tags: `values.yaml` pins both at `1.0.0` and Renovate bumps
 them from there. `migrations` has no `tag` of its own — see the appVersion note above.

ci/build-docs.sh

@@ -0,0 +1,78 @@
+#!/usr/bin/env bash
+# Build the docs zip for a chart release.
+#
+#   ci/build-docs.sh [<chart-version>]
+#
+# Copies doc/ into a build dir, fills the VALUES:BEGIN/VALUES:END markers with a
+# reference table generated from values.yaml, and packages the result as
+# ister-chart-docs-<version>.zip in the repo root. The committed chapters keep the
+# markers empty — the table exists only inside the zip, so it can never go stale
+# against values.yaml. Runs fine outside CI.
+set -euo pipefail
+
+cd "$(dirname "$0")/.."
+root="$PWD"
+
+version="${1:-$(grep -oP '^version:\s*\K\S+' Chart.yaml)}"
+version="${version#v}"
+zip_name="ister-chart-docs-${version}.zip"
+
+build_dir="$(mktemp -d)"
+trap 'rm -rf "$build_dir"' EXIT
+cp -r doc "$build_dir/doc"
+
+echo "=== generating the values reference from values.yaml"
+# python3 rather than yq, for the same reason as release-notes.sh: this must run on
+# any dev box. Leaves are dict-less values; lists count as leaves so the example-heavy
+# ones (libraries, mediaVolumes, extraEnv) show up as one row, not an explosion.
+python3 - values.yaml > "$build_dir/values-table.md" <<'PY'
+import json, sys, yaml
+
+values = yaml.safe_load(open(sys.argv[1]))
+
+def rows(node, path):
+    for key, value in node.items():
+        here = path + [key]
+        if isinstance(value, dict) and value:
+            yield from rows(value, here)
+        else:
+            yield ".".join(here), json.dumps(value)
+
+print("| Key | Default |")
+print("|---|---|")
+for key, default in rows(values, []):
+    print(f"| `{key}` | `{default}` |")
+PY
+
+echo "=== filling the markers"
+python3 - "$build_dir/doc" "$build_dir/values-table.md" <<'PY'
+import pathlib, sys
+
+doc_dir = pathlib.Path(sys.argv[1])
+table = pathlib.Path(sys.argv[2]).read_text().rstrip("\n")
+BEGIN, END = "<!-- VALUES:BEGIN", "<!-- VALUES:END -->"
+
+filled = 0
+for chapter in sorted(doc_dir.rglob("*.md")):
+    text = chapter.read_text()
+    if BEGIN not in text and END not in text:
+        continue
+    # One well-formed pair per chapter, or the build fails rather than shipping a
+    # half-substituted document.
+    if text.count(BEGIN) != 1 or text.count(END) != 1:
+        sys.exit(f"{chapter}: expected exactly one VALUES:BEGIN/VALUES:END pair")
+    head, rest = text.split(BEGIN, 1)
+    begin_line, rest = rest.split("\n", 1)
+    _, tail = rest.split(END, 1)
+    chapter.write_text(f"{head}{BEGIN}{begin_line}\n{table}\n{END}{tail}")
+    filled += 1
+
+if filled == 0:
+    sys.exit("no chapter carries the VALUES markers — nothing to fill")
+print(f"filled the values table into {filled} chapter(s)", file=sys.stderr)
+PY
+
+echo "=== packaging $zip_name"
+rm -f "$root/$zip_name"
+(cd "$build_dir" && zip -qr "$root/$zip_name" doc -x '*/.gitkeep')
+unzip -l "$root/$zip_name"

doc/README.md

@@ -0,0 +1,30 @@
+# Ister chart documentation
+
+This directory holds the administrator documentation for the ister Helm chart, laid out
+the same way as the player repo's `doc/`.
+
+## Contents
+
+- `admin/en/` — the administrator guide in English (installation, architecture, values)
+- `admin/nl/` — de beheerdershandleiding in het Nederlands (same chapters, translated)
+
+## The generated values reference
+
+Each chapter that ends in a values reference carries an empty pair of HTML-comment
+markers, `VALUES:BEGIN` and `VALUES:END` (spelled out only in the chapters themselves —
+reproducing them here would get this README a table too).
+
+The markers stay empty in git. `ci/build-docs.sh` fills them with a table generated from
+`values.yaml` when it builds the zip, so the shipped reference always matches the
+release it accompanies. Never hand-edit between the markers.
+
+## Building the docs zip locally
+
+```sh
+ci/build-docs.sh            # version taken from Chart.yaml
+ci/build-docs.sh 0.0.0-local
+```
+
+This writes `ister-chart-docs-<version>.zip` in the repo root (git-ignored) and leaves
+the committed chapters untouched. The release workflow runs the same script and attaches
+the zip to every GitHub Release.

doc/admin/en/01-installation-helm.md

@@ -0,0 +1,141 @@
+# Installing ister with Helm
+
+This chapter explains how the ister Helm chart works and how to install it. The chart
+deploys the full ister media server: the API server, the web player, and — unless you
+bring your own — PostgreSQL, RabbitMQ and Typesense.
+
+## What the chart deploys
+
+| Component | What it is | Bundled by default? |
+|---|---|---|
+| server | The Spring Boot backend (`ghcr.io/ister-app/server`) | always |
+| website | The web player (`ghcr.io/ister-app/player`) | always |
+| PostgreSQL | The database | yes (`database.mode: internal`) |
+| RabbitMQ | The message broker (Bitnami subchart) | yes (`rabbitmq.enabled: true`) |
+| Typesense | The search engine | yes (`typesense.enabled: true`) |
+| Flyway | Database migrations (`ghcr.io/ister-app/migrations`) | runs as an init container |
+
+The defaults deploy a self-contained ister with no ingress and no media volumes — enough
+to try it out, not a production setup.
+
+## Prerequisites
+
+- A Kubernetes cluster and Helm 3.
+- A [TMDB API key](https://www.themoviedb.org/settings/api) for movie/show metadata.
+- An OIDC issuer (for example Keycloak) — ister does not manage users itself.
+- For `database.mode: cnpg`: the [CloudNativePG](https://cloudnative-pg.io/) operator.
+- For ingress with TLS: an ingress controller and, optionally, cert-manager.
+
+## Installing
+
+The chart is published as an OCI artifact:
+
+```sh
+helm install ister oci://ghcr.io/ister-app/charts/ister \
+  --namespace ister --create-namespace \
+  --set server.tmdbApiKey=<your-key> \
+  --set server.oidc.url=https://keycloak.example.com/realms/auth
+```
+
+For anything beyond a first try, start from `values-production.example.yaml` in the
+[chart repository](https://github.com/ister-app/chart) and install with `-f`. Pin a chart
+version with `--version`; a GitHub Release exists for every chart version with release
+notes listing the exact image versions it deploys.
+
+## Bundled or external datastores
+
+Everything backing the server can either be deployed by the chart or pointed at an
+existing service. Whatever you choose, the templates downstream never notice the
+difference — that is the chart's central design rule.
+
+### PostgreSQL — `database.mode`
+
+- `internal` — a single postgres Deployment + PVC. Development only: one instance, no
+  backups.
+- `cnpg` — a CloudNativePG `Cluster` (3 instances by default, anti-affinity, optional
+  Barman Cloud backups to S3 under `database.cnpg.backup`). Requires the CNPG operator.
+- `external` — an existing PostgreSQL, configured under `database.external`.
+
+All three modes converge on **one Secret with the keys `host`, `port`, `dbname`, `user`,
+`password`** — the shape CNPG generates for its `<cluster>-app` Secret, which the other
+two modes hand-write to match. If you bring your own Secret (`existingSecret`), it must
+have exactly those keys; for a CNPG cluster managed outside this chart, its `<cluster>-app`
+Secret already does.
+
+### RabbitMQ — `rabbitmq.enabled`
+
+`true` deploys the Bitnami RabbitMQ subchart (everything under `rabbitmq:` is passed
+straight to it). `false` uses the `externalRabbitmq` block instead — its `existingSecret`
+needs the key `rabbitmq-password`.
+
+### Typesense — `typesense.enabled`
+
+`true` deploys Typesense with its own PVC. `false` uses `typesense.external` — its
+`existingSecret` needs the key `api-key`.
+
+## Secrets and passwords
+
+- **Nothing secret belongs in a values file.** Every credential has an `existingSecret`
+  escape hatch; use it (or a secret manager) anywhere that matters.
+- **Generated passwords survive upgrades.** When you let the chart generate a password,
+  it looks up the live Secret on upgrade and keeps the existing value — otherwise every
+  `helm upgrade` would lock the server out of its own database. This is also why
+  `helm template` output differs from what `helm install` actually applies.
+- **Rotating a Secret restarts the server.** All credentials are hashed into a
+  `checksum/secrets` pod annotation, so a changed Secret rolls the Deployment.
+
+## Database migrations
+
+Flyway runs as an **init container on the server pod** (preceded by a `wait-for-db`
+container), so the server can never start against an unmigrated schema. It is not a Helm
+hook on purpose: with a bundled database, a pre-install hook would wait for a database
+that Helm has not created yet. The migrations image publishes the same version as the
+server, so `flyway.image.tag` stays empty and follows the server version automatically.
+
+## Media libraries and volumes
+
+Two value lists connect the server to your media:
+
+- `server.libraries` — the libraries ister scans; each has a `name` and a `type`
+  (`SHOW`, `MOVIE`, `MUSIC`, `BOOK`, `PODCAST`, `COMIC`).
+- `server.mediaVolumes` — the volumes mounted into the server pod, each backed by exactly
+  one of `hostPath`, `existingClaim` or `nfs`, and linked to a library via `library`
+  (omit it for a mount-only volume). **No trailing slash on `mountPath`** — the scanner
+  skips the tree if there is one.
+
+Two more storage knobs matter:
+
+- `cache` — a PVC for the server's cache directory (transcodes, images). It is
+  `ReadWriteOnce` by default, which is why `server.replicaCount` must stay at 1 — the
+  chart refuses to render more replicas unless you switch to `ReadWriteMany`.
+- `server.tmp` — scratch space for transcoding. Disable it when `mountPath` falls inside
+  one of your media volumes, or the dedicated volume shadows that path.
+
+## Ingress
+
+`ingress.enabled: true` publishes the player at `/` and the API at `server.contextPath`
+(default `/api`) on `ingress.host`, with TLS via cert-manager when
+`ingress.tls.certIssuer` is set. `ingress.wellKnown.enabled` additionally serves
+`/.well-known/ister` for client discovery — implemented as an ingress-nginx
+server-snippet, which modern ingress-nginx disables by default
+(`allow-snippet-annotations`); enable that on the controller first.
+
+## Operations
+
+- **Upgrades**: `helm upgrade ister oci://ghcr.io/ister-app/charts/ister --version <v>`
+  with your values file. Generated passwords are preserved (see above).
+- **Smoke test**: `helm test ister -n ister --logs` runs the shipped connectivity test.
+- **Monitoring**: `monitoring.enabled` renders a Prometheus Operator ServiceMonitor for
+  the server's actuator; in `cnpg` mode, `database.cnpg.podMonitor` covers the database.
+- **Uninstall**: the database, cache and Typesense PVCs are kept by default
+  (`retain: true`) so an uninstall is not destructive; set `retain: false` where you
+  want them purged with the release.
+
+## Values reference
+
+Every value the chart accepts, with its default. This table is generated from the
+`values.yaml` of the release this documentation shipped with; `values.schema.json`
+enforces the same contract on every render.
+
+<!-- VALUES:BEGIN (generated by ci/build-docs.sh — do not edit between the markers) -->
+<!-- VALUES:END -->