Merge branch 'main' into feat/186-otel-endpoint

refs #173. This is the minimum step from the issue: the site is now **built** in CI, not **published**. Publishing still needs an ADR (Gitea has no built-in Pages) or a CLAUDE.md §12 correction, so the issue stays open.

- `make docs`: creates a throwaway `.venv-docs`, installs pinned `mkdocs==1.6.1` and `mkdocs-material==9.7.7`, then runs `mkdocs build --strict`. The target is also added to `make ci`.
- New `docs` job in `ci.yaml` (`setup-python@v5`, then `make docs`).
- Red, then green: the first commit fails on a link from `runbooks/ci.md` to a file outside `docs/`; the second turns that link into plain code.

**Dependency (§13):** mkdocs and mkdocs-material were already the site's declared toolchain (`mkdocs.yml`) but were never installed anywhere. They give a strict link/nav/theme check. Replacing them means writing our own Markdown link checker, and `check-docs-nav.py` already covers only the nav half. Risk: Material warns that MkDocs 2.0 drops its plugin/theme system, so both are pinned exactly. No ADR, since this adds no new decision beyond what `mkdocs.yml` already assumes.

Verified locally: `make docs` → `Documentation built in 0.87 seconds`.

🤖 Generated with [Claude Code](https://claude.com/claude-code)Reviewed-on: #189

.gitea/workflows/ci.yaml

@@ -98,6 +98,17 @@ jobs:
           [ -n "${GITHUB_STEP_SUMMARY:-}" ] || exit 0
           python3 infra/trx-summary.py TestResults >> "$GITHUB_STEP_SUMMARY"
 
+  # The docs site must build with --strict (#173). setup-python so `make docs` can
+  # create its venv regardless of what the runner image ships.
+  docs:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: https://github.com/actions/checkout@v4
+      - uses: https://github.com/actions/setup-python@v5
+        with:
+          python-version: '3.12'
+      - run: make docs
+
   # Frontend (Nx/Angular) lane: install with pnpm, then Nx lint + test + build.
   frontend:
     runs-on: ubuntu-latest
@@ -207,8 +218,14 @@ jobs:
   # dispatched (gitea-actions-gotchas.md §7). Default `if: success()` dispatches normally. Cost: a
   # failing mutation ratchet now skips verify-stack instead of running it anyway; the fix-and-re-push
   # re-run exercises verify-stack, so we still get the signal.
+  #
+  # Main only, not on PRs: the runner shares the lab node with the deployed stack, and a second
+  # full stack per PR was what got the runner OOM-killed (#182). PRs still gate on every job above;
+  # the live-stack check runs once per merge. A plain event `if` keeps the implicit success(), so it
+  # is not the status-function case from gotchas §7.
   verify-stack:
     needs: [mutation]
+    if: github.event_name == 'push' && github.ref == 'refs/heads/main'
     runs-on: ubuntu-latest
     steps:
       - uses: https://github.com/actions/checkout@v4

.gitea/workflows/deploy.yaml

@@ -34,6 +34,9 @@ jobs:
       # `true` fills in the medewerker OTP step for the public demo (chart value
       # demo.otpAutofill). The fixture secret is committed: demo only.
       OTP_AUTOFILL: ${{ vars.OTP_AUTOFILL }}
+      # Tempo for the services' traces, e.g. http://tempo.monitoring.svc:4317 (the
+      # cluster monitoring stack, Infra repo). Empty = the chart default.
+      OTEL_ENDPOINT: ${{ vars.OTEL_ENDPOINT }}
     steps:
       - uses: https://github.com/actions/checkout@v4
 
@@ -100,7 +103,7 @@ jobs:
           make k8s-reseed \
             TALOS_HOST=${TALOS_HOST:-localhost} \
             K8S_REGISTRY=${TALOS_VM_IP:-192.168.122.173}:30500 \
-            K8S_SET="${KEYCLOAK_URL:+--set keycloakUrl=$KEYCLOAK_URL} --set demo.otpAutofill=${OTP_AUTOFILL:-false}"
+            K8S_SET="${KEYCLOAK_URL:+--set keycloakUrl=$KEYCLOAK_URL} --set demo.otpAutofill=${OTP_AUTOFILL:-false}${OTEL_ENDPOINT:+ --set otelEndpoint=$OTEL_ENDPOINT}"
 
       # `dev` is a mutable tag and helm sees an unchanged pod template, so the
       # new images only land on a restart (pullPolicy is already Always).

.gitignore

@@ -61,3 +61,7 @@ __pycache__/
 TestResults/
 test-output/
 tests/e2e/playwright-report.json
+
+# MkDocs build (`make docs`)
+.venv-docs/
+site/

Makefile

@@ -43,11 +43,11 @@ export DOCKER_HOST := unix://$(PODMAN_SOCK)
 endif
 endif
 
-.PHONY: ci lint build unit mutation frontend integration verify verify-up verify-acl verify-nrc verify-projection verify-bff verify-domain verify-observability verify-tracing verify-metrics verify-objecttypen verify-objecten verify-registerrecord verify-objecten-notifications verify-notifications smoke up down local verify-local local-down changelog openzaak-up openzaak-smoke openzaak-seed openzaak-down stack-up stack-smoke stack-down keycloak-up keycloak-smoke keycloak-down flowable-up flowable-smoke flowable-down k8s-lint k8s-drift k8s-registry k8s-images k8s-seed k8s-up k8s-reseed k8s-portals k8s-down k8s-purge help
+.PHONY: ci lint build unit mutation frontend docs integration verify verify-up verify-acl verify-nrc verify-projection verify-bff verify-domain verify-observability verify-tracing verify-metrics verify-objecttypen verify-objecten verify-registerrecord verify-objecten-notifications verify-notifications smoke up down local verify-local local-down changelog openzaak-up openzaak-smoke openzaak-seed openzaak-down stack-up stack-smoke stack-down keycloak-up keycloak-smoke keycloak-down flowable-up flowable-smoke flowable-down k8s-lint k8s-drift k8s-registry k8s-images k8s-seed k8s-up k8s-reseed k8s-portals k8s-down k8s-purge help
 
 ## ci: run the full pipeline — lint, build, unit, mutation, frontend, verify (mirrors Gitea Actions)
 ## `verify` is the live-stack stage (full stack up once → ACL + notification checks).
-ci: lint build unit mutation frontend verify
+ci: lint build unit mutation frontend docs verify
 
 ## frontend: install deps and run the Nx lint/test/build for the portals (pnpm + Node required)
 # Tests run in their own phase, ahead of the build. The @angular/build:unit-test
@@ -81,6 +81,15 @@ unit:
 	python3 infra/test_playwright_summary.py
 	python3 infra/test_portal_caddyfiles.py
 
+## docs: build the MkDocs site with --strict (a broken link or nav entry fails)
+# Pinned in a throwaway venv: Material 9.7 is the last line on MkDocs 1.x, and MkDocs
+# 2.0 drops the plugin/theme system this site relies on. Publishing is a separate
+# decision (#173); this only proves the site builds.
+docs:
+	python3 -m venv .venv-docs
+	.venv-docs/bin/pip install --quiet mkdocs==1.6.1 mkdocs-material==9.7.7
+	.venv-docs/bin/mkdocs build --strict
+
 ## mutation: run the Stryker.NET ratchet on each service with branching logic (fails below baseline)
 # Stryker is pinned as a local dotnet tool (.config/dotnet-tools.json); `tool restore`
 # makes `make mutation` work from a fresh clone. Each service owns its config + break

docs/architecture/adr-0035-public-access-through-the-labs-caddy.md

@@ -0,0 +1,108 @@
+# ADR-0035: The deployed stack is published through the existing labs Caddy
+
+- **Status:** Accepted
+- **Date:** 2026-09-25
+- **Deciders:** Respellion engineering
+- **Slice:** [#177](https://git.labs.respellion.tech/eho/register-referentie/issues/177) —
+  that issue proposed the opposite (an in-cluster Caddy edge); this ADR records why the
+  host-side option won. Implemented in #179, #180 and #181.
+
+## Context
+
+The stack deploys to a single-node Talos VM (ADR-0033, #175). Until now it was only usable
+through five SSH port-forwards: the portals' OIDC flow uses PKCE, PKCE needs
+`crypto.subtle`, and browsers expose that only in a **secure context**, meaning HTTPS or a
+`localhost` origin. A NodePort on the VM's address is neither. We want a URL a demo
+audience can simply open.
+
+Three facts about where things run shape the answer:
+
+- The Talos VM is a libvirt guest on a **Fedora hypervisor in the office**, behind NAT
+  with no public address. The only way in from outside is an existing reverse SSH tunnel
+  (`autossh-reverse-tunnel.service`) into an `openssh-server` container on the labs
+  server.
+- The **labs server** (public IP) already runs Caddy for `*.labs.respellion.tech`, with
+  the wildcard certificate (DNS-01 via Cloudflare) and ports 80/443. Every other labs
+  service is published there (repo `Infra`, `infra/development/`).
+- #177 proposed a Caddy **inside the cluster**, fed by a layer-4 forward on the host, so
+  that routing and certificates would be cluster state. That assumes the public IP is on
+  the hypervisor. It isn't: the hypervisor has no inbound path, and 80/443 on the labs
+  server are already taken by the labs Caddy.
+
+## Decision
+
+**Publish the portals and Keycloak through the existing labs Caddy. Carry the traffic to
+the cluster over a second reverse SSH tunnel from the hypervisor.**
+
+```
+browser ─https─▶ labs Caddy ─▶ openssh-server:3014x/30180
+        ─reverse SSH tunnel─▶ Fedora hypervisor ─▶ Talos NodePorts
+```
+
+- **Hostnames** under the existing wildcard: `big-register` (openbaar), `big-mijn`
+  (self-service), `big-behandel`, `big-beheer`, and `big-auth` (Keycloak, with `/admin*`
+  answered 404).
+- **Tunnel:** `big-portals-tunnel.service` on the hypervisor (repo `Infra`)
+  reverse-forwards the five browser-facing NodePorts into `openssh-server`. It is
+  separate from the access tunnel on `:6667`, so a failed forward can't cut SSH access.
+  Caddy joins the `openssh_default` network to reach the tunnel ends.
+- **Keycloak's issuer** is the public origin. The chart value `keycloakUrl` replaces
+  `host` + NodePort in one helper, `big.keycloakUrl`, which feeds both `KC_HOSTNAME` and
+  the portals' `config.json` authority, so the two cannot drift (ADR-0010). The deploy
+  workflow sets it from the `KEYCLOAK_URL` repository variable.
+- **`KC_PROXY_HEADERS=xforwarded`:** `KC_HOSTNAME_BACKCHANNEL_DYNAMIC` builds the token,
+  userinfo and certs URLs from the request. That request reaches Keycloak as plain HTTP,
+  so the URLs came out `http://` and browsers blocked them as mixed content. Trusting
+  Caddy's `X-Forwarded-Proto` keeps them HTTPS. In-cluster calls send no such header and
+  still use `keycloak:8080`.
+- **Demo MFA (optional):** `demo.otpAutofill` (`OTP_AUTOFILL`) makes the `big-demo` theme
+  (`infra/keycloak/themes/big-demo`) Keycloak's default. Its script fills in and submits
+  the medewerker OTP from the fixture secret (ADR-0031), so the step is visibly enforced
+  without an authenticator. It is off by default.
+
+### Alternatives considered
+
+- **In-cluster Caddy edge (#177, PR #178).** It would keep routes and certificates in
+  cluster state. But it needs a public inbound path to the hypervisor that doesn't exist,
+  plus a second certificate authority beside the labs Caddy, which already holds the
+  wildcard. Closed unmerged.
+- **Port-forward on the office router to the hypervisor.** This opens the office network
+  itself to the internet. Rejected.
+- **Move the cluster to a host with a public IP.** It would remove the tunnel, but it's a
+  bigger change than publishing one demo. It remains the natural step if the stack
+  outgrows a lab VM.
+- **Keep the SSH port-forwards.** Fine for one developer, but not something you can send
+  to someone.
+
+## Consequences
+
+**Positive**
+
+- Real hostnames and HTTPS, so PKCE works in any browser with no client-side setup.
+- No new certificate handling: the labs Caddy's wildcard covers the new hosts.
+- The chart stays edge-agnostic. With `keycloakUrl` empty it renders exactly as before,
+  so compose, CI and the `localhost` workflow are untouched.
+
+**Negative / costs**
+
+- **Routing lives outside the cluster**, in the Infra repo's Caddyfile. That is exactly
+  what #177 wanted to avoid. Adding a portal means changing three places: a NodePort in
+  the chart, a forward in the tunnel unit, and a host in the Caddyfile.
+- **Two SSH hops in the data path.** If the hypervisor or the tunnel is down, the
+  portals return 502 even though the cluster is healthy.
+- **One issuer string.** With `keycloakUrl` set, the `localhost` port-forward workflow
+  (runbook §5) can no longer log in.
+- **Keycloak trusts `X-Forwarded-*`** from anything that reaches it. Today that is only
+  in-cluster callers and the tunnel. `KC_PROXY_TRUSTED_ADDRESSES` can narrow it if the
+  NodePort is ever exposed more widely.
+- **The portals are public.** Anyone with the link can log in with the committed test
+  credentials, and with `OTP_AUTOFILL` on, no second factor stands in the way. That is
+  acceptable for synthetic data. Put the labs Caddy's Azure `authorize` in front of the
+  `big-*` hosts if the audience must be restricted.
+
+**Follow-up**
+
+- Runbook: `docs/runbooks/kubernetes-talos.md`, "Publishing through the labs Caddy".
+- Dev-mode Keycloak generates new signing keys on every restart, and the BFF re-fetches
+  them at most every 5 minutes, so expect a few minutes of 401s after a Keycloak restart.
+  Persisting Keycloak's database (runbook §6) would remove that.

docs/runbooks/ci.md

@@ -19,9 +19,10 @@ and CI cannot drift:
 | `build` | `make build` → `dotnet build … -c Release` | .NET 10 SDK |
 | `unit` | `make unit` → `dotnet test … -c Release --filter "Category!=Integration"` | .NET 10 SDK |
 | `frontend` | `make frontend` → Nx lint/test/build for the four portals | pnpm + Node |
+| `docs` | `make docs` → `mkdocs build --strict` in a pinned venv (fails on a broken link or nav entry; the site is not published yet, #173) | Python 3 |
 | `k8s` | `make k8s-lint` (render + schema-check the Helm chart) → `make k8s-drift` (chart still describes the same stack as `infra/docker-compose.yml`) | pinned `helm` binary + `docker compose` |
 | `mutation` | `make mutation` → `dotnet tool restore` → `dotnet stryker` (ACL); uploads the HTML report as an artifact | .NET 10 SDK |
-| `verify-stack` | the single live-stack stage — steps: `make verify-up` (full stack up + health, the DoD smoke) → `make verify-acl` (ACL ↔ OpenZaak) → `make verify-nrc` (OpenZaak → NRC delivery) → `make down` | container engine + egress (base images, nuget, `selectielijst.openzaak.nl`) |
+| `verify-stack` | **push to `main` only, skipped on PRs** (#182) — the single live-stack stage — steps: `make verify-up` (full stack up + health, the DoD smoke) → `make verify-acl` (ACL ↔ OpenZaak) → `make verify-nrc` (OpenZaak → NRC delivery) → `make down` | container engine + egress (base images, nuget, `selectielijst.openzaak.nl`) |
 
 > **Why one `verify-stack` job, not three.** The single self-hosted runner runs jobs
 > **sequentially**, so booting OpenZaak once (instead of once per check) is the
@@ -57,9 +58,12 @@ dotnet tool (`.config/dotnet-tools.json`), so it runs identically locally and in
 make mutation     # dotnet tool restore + dotnet stryker on the ACL
 ```
 
-Config lives in [`services/acl/stryker-config.json`](../../services/acl/stryker-config.json).
+Config lives in `services/acl/stryker-config.json`.
 It runs in **solution mode** against `Acl.slnx`, mutating the two projects under test
 (`Acl.Application`, `Acl.Infrastructure`); `Acl.Api` has no tests and is skipped.
+`Acl.slnx` leaves out `Acl.IntegrationTests`: it needs a live OpenZaak, and Stryker
+runs every test project in the solution, so keeping it in makes 8 tests fail in the
+initial run (#174).
 
 **Baseline (the ratchet):** the ACL is the first service with branching logic, so it
 sets the repo-wide baseline. Observed score **95%**; enforced `break` threshold **90%**

docs/runbooks/kubernetes-talos.md

@@ -403,6 +403,8 @@ upgrade path.
 
 ## Publishing through the labs Caddy
 
+Why this route and not an in-cluster edge: [ADR-0035](../architecture/adr-0035-public-access-through-the-labs-caddy.md).
+
 The portals can be reached on real hostnames through the Caddy that already fronts
 `*.labs.respellion.tech` (repo `Infra`, `infra/development/`). The chain:
 

infra/helm/big-reference/values.yaml

@@ -30,6 +30,12 @@ host: 192.168.122.100
 # portals' authority (runbook, "Publishing through the labs Caddy").
 keycloakUrl: ""
 
+# Where the .NET services send traces (OTLP gRPC). The default is the chart's own
+# `tempo` workload (off by default, like compose). Point it at a Tempo outside the
+# release, e.g. the cluster monitoring stack's http://tempo.monitoring.svc:4317 —
+# with no Tempo at all, every export fails and is counted as a .NET exception.
+otelEndpoint: http://tempo:4317
+
 demo:
   # Fill in and submit the medewerker OTP step from the fixture secret, so a public
   # demo shows MFA enforced without an authenticator: makes the big-demo theme
@@ -160,10 +166,11 @@ envGroups:
     NOTIFICATIONS_DISABLED: "false"
     RUN_SETUP_CONFIG: "true"
 
-  # Traces for the .NET services. Always set, like compose: the exporter fails
-  # harmlessly when Tempo is absent (services/*/Program.cs).
+  # Traces for the .NET services. Always set, like compose. With no Tempo behind
+  # `otelEndpoint` the exporter fails quietly but throws on every batch, which
+  # shows up as HttpRequestException/SocketException in dotnet_exceptions_total.
   otel:
-    OTEL_EXPORTER_OTLP_ENDPOINT: http://tempo:4317
+    OTEL_EXPORTER_OTLP_ENDPOINT: '{{ .Values.otelEndpoint }}'
     OTEL_EXPORTER_OTLP_PROTOCOL: grpc
 
 # ── Workloads ──────────────────────────────────────────────────────────────────
@@ -286,6 +293,11 @@ workloads:
       # Only rendered with demo.otpAutofill (big.env skips empty values); off, Keycloak
       # keeps its stock theme and the mounted big-demo theme is unused.
       KC_SPI_THEME_DEFAULT: '{{ if .Values.demo.otpAutofill }}big-demo{{ end }}'
+      # Behind a TLS proxy (keycloakUrl) the dynamic backchannel URLs — token,
+      # userinfo, certs — take their scheme from the request, which reaches Keycloak
+      # as plain http; trusting X-Forwarded-Proto keeps them https so the browser
+      # doesn't block them as mixed content. In-cluster calls send no such header.
+      KC_PROXY_HEADERS: xforwarded
     ports: [{ name: http, port: 8080 }]
     # TCP, not /health/ready on the management port: nothing here gates on realm
     # import, and a wrong health path would leave the Service with no endpoints.

mkdocs.yml

@@ -56,6 +56,7 @@ nav:
       - "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
+      - "ADR-0035: Public access through the labs Caddy": architecture/adr-0035-public-access-through-the-labs-caddy.md
   - FDS-architectuur:
       - Overzicht: architecture/fds/README.md
       - Componentview (L3): architecture/fds/c4-component-view.md

services/acl/Acl.slnx

@@ -1,7 +1,9 @@
 <Solution>
+  <!-- Stryker-only. Acl.IntegrationTests is left out on purpose: it needs a live
+       OpenZaak, so in the mutation job it fails its initial run (#174). The root
+       register-referentie.slnx still builds and lints it. -->
   <Project Path="Acl.Api/Acl.Api.csproj" />
   <Project Path="Acl.Application/Acl.Application.csproj" />
   <Project Path="Acl.Infrastructure/Acl.Infrastructure.csproj" />
-  <Project Path="Acl.IntegrationTests/Acl.IntegrationTests.csproj" />
   <Project Path="Acl.Tests/Acl.Tests.csproj" />
 </Solution>