docs(nav): point the landing page at the Kubernetes runbook (refs #169 )

docs(nav): publish every ADR and runbook, not just the first ten (refs #169 )
ADR-0011 through ADR-0034, six of the seven runbooks (OpenZaak, Open Notificaties, Keycloak, Flowable, Kubernetes-on-Talos, Gitea Actions gotchas) and synthetic-data.md are now in mkdocs.yml's nav, which makes `make lint` green again. Also fills in ADR-0033's `Slice:` header, which said "none yet" — #25 closed it.
2026-09-10 11:04:08 +02:00 · 2026-09-10 11:03:39 +02:00 · 2026-09-10 11:02:52 +02:00 · 2026-09-10 08:53:58 +00:00
5 changed files with 68 additions and 2 deletions
@@ -64,6 +64,9 @@ frontend:
 ## lint: verify formatting (no changes)
 lint:
 	dotnet format $(SLN) --verify-no-changes
+	# Only pages in mkdocs.yml's nav are published, and mkdocs keeps a build green
+	# when one is missing — so the nav is checked here rather than not at all.
+	python3 infra/check-docs-nav.py

 ## build: release build
 build:
@@ -3,8 +3,8 @@
 - **Status:** Accepted
 - **Date:** 2026-09-04
 - **Deciders:** Respellion engineering
- **Slice:** _(none yet — raised directly as a deployment-target request; see
-  "Process note" at the end)_
+- **Slice:** #25 (S-24) — raised directly as a deployment-target request and matched to
+  that issue afterwards; see the "Process note" at the end

 ## Context

@@ -14,6 +14,8 @@ should teach.
  In Dutch; the strategic framing lives in `Respellion/innovation-lab`.
 - **[Working in Gitea](gitea-workflow.md)** — issues, milestones, branches, PRs.
 - **[CI runbook](runbooks/ci.md)** — the pipeline and the `make ci` local gate.
+- **[Kubernetes on Talos](runbooks/kubernetes-talos.md)** — the second deployment target:
+  one Helm chart, a single-node cluster, and the parts that bite (ADR-0033).

 ## Quickstart

@@ -0,0 +1,30 @@
+#!/usr/bin/env python3
+"""Fail when a page under docs/ is missing from mkdocs.yml's nav.
+
+docs/ is the source of truth (CLAUDE.md §12), but only the pages listed in the nav
+are published — and mkdocs' own `omitted_files: warn` keeps a build green while
+silently dropping them, which is how every ADR after 0010 and every runbook but
+ci.md fell off the site.
+
+ponytail: a substring test, not a YAML parse — a page's path either appears in
+mkdocs.yml or it doesn't, and that needs no dependency.
+"""
+
+import sys
+from pathlib import Path
+
+ROOT = Path(__file__).resolve().parents[1]
+nav = (ROOT / "mkdocs.yml").read_text()
+
+missing = sorted(
+    str(page.relative_to(ROOT / "docs"))
+    for page in (ROOT / "docs").rglob("*.md")
+    if str(page.relative_to(ROOT / "docs")) not in nav
+)
+
+if missing:
+    print(f"{len(missing)} page(s) under docs/ are not in mkdocs.yml's nav:")
+    print("\n".join(f"  {m}" for m in missing))
+    sys.exit(1)
+
+print("docs nav complete: every page under docs/ is published")
@@ -32,6 +32,30 @@ nav:
      - "ADR-0008: Read projection store": architecture/adr-0008-read-projection-store.md
      - "ADR-0009: External-task job worker": architecture/adr-0009-external-task-job-worker.md
      - "ADR-0010: BFF OIDC validation": architecture/adr-0010-bff-oidc.md
+      - "ADR-0011: Approval status flow": architecture/adr-0011-approval-status-flow.md
+      - "ADR-0012: Citizen reference correlation": architecture/adr-0012-citizen-reference-correlation.md
+      - "ADR-0013: Behandel-portal wiring": architecture/adr-0013-behandel-portal-wiring.md
+      - "ADR-0014: Withdrawal cancels the process": architecture/adr-0014-withdrawal-cancels-the-process.md
+      - "ADR-0015: Beoordeling escalation": architecture/adr-0015-beoordeling-escalation.md
+      - "ADR-0016: Diploma eligibility DMN": architecture/adr-0016-diploma-eligibility-dmn.md
+      - "ADR-0017: Document-wait timeout": architecture/adr-0017-document-wait-timeout-cancellation.md
+      - "ADR-0018: Diploma upload via the ACL": architecture/adr-0018-diploma-upload-via-acl-documenten.md
+      - "ADR-0019: Zaak cancellation on timeout": architecture/adr-0019-zaak-cancellation-on-timeout.md
+      - "ADR-0020: Local stack self-seeds": architecture/adr-0020-local-stack-self-seeds.md
+      - "ADR-0021: Zaaktype by identificatie": architecture/adr-0021-acl-resolves-zaaktype-by-identificatie.md
+      - "ADR-0022: Quartz scheduler": architecture/adr-0022-quartz-scheduler.md
+      - "ADR-0023: Observability stack": architecture/adr-0023-observability-stack.md
+      - "ADR-0024: Prometheus AspNetCore exporter": architecture/adr-0024-prometheus-aspnetcore-exporter.md
+      - "ADR-0025: BFF reads catalogus via the ACL": architecture/adr-0025-bff-reads-catalogus-via-acl.md
+      - "ADR-0026: Mutable default-fill store": architecture/adr-0026-mutable-default-fill-store.md
+      - "ADR-0027: RegisterRecord objecttype": architecture/adr-0027-registerrecord-objecttype-schema.md
+      - "ADR-0028: Objecten holds the register": architecture/adr-0028-objecten-holds-the-register.md
+      - "ADR-0029: Objecten publishes to NRC": architecture/adr-0029-objecten-publishes-to-nrc.md
+      - "ADR-0030: Projection sourced from the register": architecture/adr-0030-projection-sourced-from-the-register.md
+      - "ADR-0031: MFA on the medewerker realm": architecture/adr-0031-mfa-on-the-medewerker-realm.md
+      - "ADR-0032: Werkbak live refresh": architecture/adr-0032-werkbak-live-refresh.md
+      - "ADR-0033: Kubernetes via one Helm chart": architecture/adr-0033-kubernetes-via-one-helm-chart.md
+      - "ADR-0034: Caddy serves the portals": architecture/adr-0034-caddy-serves-the-portals.md
  - FDS-architectuur:
      - Overzicht: architecture/fds/README.md
      - Componentview (L3): architecture/fds/c4-component-view.md
@@ -46,8 +70,15 @@ nav:
  - Working in Gitea: gitea-workflow.md
  - Frontend decisions: frontend-decisions.md
  - Demo script: demo-script.md
+  - Synthetic data: synthetic-data.md
  - Runbooks:
      - CI: runbooks/ci.md
+      - OpenZaak: runbooks/openzaak.md
+      - Open Notificaties (NRC): runbooks/opennotificaties.md
+      - Keycloak: runbooks/keycloak.md
+      - Flowable: runbooks/flowable.md
+      - Kubernetes on Talos: runbooks/kubernetes-talos.md
+      - Gitea Actions gotchas: runbooks/gitea-actions-gotchas.md

 markdown_extensions:
  - admonition
Author	SHA1	Message	Date
not	ab4392320a	docs(nav): point the landing page at the Kubernetes runbook (refs #169 ) CI / build (pull_request) Successful in 4m45s Details CI / lint (pull_request) Successful in 5m4s Details CI / unit (pull_request) Successful in 1m0s Details CI / frontend (pull_request) Successful in 1m56s Details CI / mutation (pull_request) Successful in 3m10s Details CI / verify-stack (pull_request) Successful in 6m8s Details	2026-09-10 11:04:08 +02:00
not	16509a399c	docs(nav): publish every ADR and runbook, not just the first ten (refs #169 ) ADR-0011 through ADR-0034, six of the seven runbooks (OpenZaak, Open Notificaties, Keycloak, Flowable, Kubernetes-on-Talos, Gitea Actions gotchas) and synthetic-data.md are now in mkdocs.yml's nav, which makes `make lint` green again. Also fills in ADR-0033's `Slice:` header, which said "none yet" — #25 closed it.	2026-09-10 11:03:39 +02:00
not	8df3faf979	test(docs): fail when a page under docs/ is missing from the nav (refs #169 ) Only the pages listed in mkdocs.yml's nav are published, and mkdocs' own `omitted_files: warn` keeps the build green while dropping the rest — so nothing ever said that the site had quietly stopped at ADR-0010 and runbooks/ci.md. Runs in `make lint` (python3 only, no new tooling), so it gates every PR through the existing job. Red: 31 pages are missing — ADR-0011 through ADR-0034, six of the seven runbooks, and synthetic-data.md.	2026-09-10 11:02:52 +02:00
not	1dd8bd4e1b	S-24/#25 · Helm chart + Kubernetes deployment, and Caddy for the portals (#166 ) (#167 ) CI / lint (push) Successful in 1m17s Details CI / build (push) Successful in 1m12s Details CI / unit (push) Successful in 1m26s Details CI / frontend (push) Successful in 2m58s Details CI / mutation (push) Successful in 9m1s Details CI / verify-stack (push) Successful in 8m53s Details ## What & why Two changes, made and verified together on a real cluster. S-24 / #25 — a Helm chart for the platform. One chart, `infra/helm/big-reference`, whose `values.yaml` is a near-literal transcription of `infra/docker-compose.yml`, rendered by three generic templates (Deployment, Job, Service) over a `workloads` map. Adding a service is a values edit. `make k8s-lint` renders and schema-checks the whole stack without a cluster. The issue asked for a sketch; this is deployed and verified end to end (see below), which is more than it asked for — the part it asked for that is not here is the production-posture write-up (HA, secrets, backup), see Known gaps. #166 — Caddy replaces nginx in the portals. nginx resolves a variable `proxy_pass` upstream itself, using only the `resolver` directive and never `/etc/resolv.conf`'s search domains. That had cost two workarounds in one script: rewriting the resolver address for rootless podman, and injecting a full FQDN so the bare `bff` name could resolve on Kubernetes. Caddy dials per request through the system resolver, so `reverse_proxy bff:8080` works on every engine unchanged; `apps/portal-nginx-resolver.sh` and the chart's `BFF_HOST` env are deleted. Closes #25 Closes #166 ## Definition of Done - [x] Linked Gitea issue (above). - [x] Failing test committed before the implementation — twice: the Caddyfile contract test before the Caddyfiles, `make k8s-lint` before the chart. - [x] Implementation makes the test pass. - [x] Conventional Commits referencing the issues (`refs #25` / `refs #166`). - [ ] CI green — awaiting the run on this PR (`make k8s-lint`, `dotnet format` and the new unit self-check pass locally; the compose e2e and mutation lanes are CI's). - [ ] `docker compose up` from a fresh clone reaches green health checks within 3 minutes — the portal images were rebuilt and verified standalone, but a full `make up` run has not been done on this branch. Please confirm in review or let CI's smoke test speak. - [x] Docs updated — `docs/runbooks/kubernetes-talos.md` (new), `frontend-decisions.md`, `demo-script.md`, and the docs that named nginx. - [x] ADR added — ADR-0033 (chart) and ADR-0034 (Caddy). - [ ] Demo note in `docs/demo-script.md` — not added: the deployment target is not a user-visible slice, and the Caddy swap is invisible to the demo script beyond the wording fix included here. ## How it was verified Brought up from scratch on a single-node Talos v1.14.0 VM (6 vCPU / 10 GB, virtio disk) under virt-manager: 29 pods ready and four bootstrap Jobs complete in under three minutes, zero restarts, using ~4.4 GB of the VM's 10 GB. - Full Common Ground path: portal Caddy → BFF → domain → Flowable → ACL → OpenZaak + Objecten → NRC → event-subscriber → projection → public register (`INGEDIEND`, reference matching the submitted registration). - Werkbak read with an MFA'd medewerker token → 200. - The browser flow driven with Playwright against `http://localhost:30140`: secure context, `crypto.subtle` present, Keycloak form reached, login completed, no console errors. - Routing checked against a stub BFF: SPA fallback serves deep links, each portal proxies its own groups, and a portal does not proxy a neighbour's group. ## Notes for reviewers Three bugs this shook out, each fixed at the cause rather than the symptom: 1. `command` vs `args`. Compose's `command:` replaces the image CMD; Kubernetes' replaces the ENTRYPOINT. Transcribing one to the other broke every upstream image that relies on its entrypoint — postgres refused to run as root, Keycloak tried to exec `start-dev`. The chart now `fail`s at render time on `command`. 2. Concurrent migrations. Both `/setup_configuration.sh` and `/start.sh` run `manage.py migrate`; compose serialises them with `depends_on`, Kubernetes has no such edge, so the init Job and its web pod raced (`relation "zgw_consumers_service" already exists`). The four Django services now do both steps in order in the web pod — which also deletes four workloads. 3. `emptyDir` databases are wiped by any pod-template change. `make k8s-reseed` now also restarts `event-subscriber` and `projection-api`, which create the projection schema on start and otherwise keep writing to a schema-less database. Known gaps / follow-ups: - Secrets. `values.yaml` carries the dev credentials in plain text (`admin/admin`, the ZGW client secret, the two Objecten tokens) and the chart has no `Secret` objects. Fine for a laptop demo, and exactly what #25's "production posture" ADR should address — I suggest a follow-up issue rather than stretching this PR. - No CI gate for the chart yet. `make k8s-lint` exists but is not wired into `.gitea/workflows/ci.yaml`, and nothing enforces that the chart and the compose file stay in step. Worth a small follow-up. - This is two slices in one PR. They were built and verified together and the diff is entangled (the chart was written against Caddy from the start), so splitting now would mean re-creating an nginx-shaped chart to throw away. Happy to split if you'd rather. - Rebased onto #161 (merged as #165) rather than merged, to keep the history linear. One conflict, in the `unit:` target where both branches add a self-check line — resolved by keeping both. #161's `infra/host-browser.yml` arrived with `/usr/share/nginx/html/config.json` and is fixed to `/usr/share/caddy/` inside the `feat(portals)` commit, so no commit on this branch leaves that overlay pointing at a path the images no longer have.Reviewed-on: #167	2026-09-10 08:53:58 +00:00