From e1883c2d0e1e020589c6fac343b90af3d987ace4 Mon Sep 17 00:00:00 2001
From: Edwin van den Houdt <eho@respellion.nl>
Date: Wed, 3 Jun 2026 15:08:00 +0200
Subject: [PATCH] chore(infra): make openzaak-* targets + runbook (refs #10)
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Add `make openzaak-up`, `make openzaak-smoke`, and `make openzaak-down` so
the OpenZaak stack is testable in one command, matching the `make ci`
pattern. openzaak-smoke polls until the API responds, then asserts auth is
enforced (403) and the admin/schema endpoints are reachable (302/200).
Document it in docs/runbooks/openzaak.md (kept out of `make ci` — it's a
heavier, separate check).

Verified: `make openzaak-smoke` is green end-to-end.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
---
 Makefile                  | 28 +++++++++++++++++++++-
 docs/runbooks/openzaak.md | 50 +++++++++++++++++++++++++++++++++++++++
 2 files changed, 77 insertions(+), 1 deletion(-)
 create mode 100644 docs/runbooks/openzaak.md

diff --git a/Makefile b/Makefile
index 4848f54..28a45dc 100644
--- a/Makefile
+++ b/Makefile
@@ -8,6 +8,8 @@
 SLN        := services/bff/Bff.slnx
 COMPOSE    := infra/docker-compose.yml
 HEALTH_URL := http://localhost:8080/health
+OZ_COMPOSE := infra/openzaak/docker-compose.yml
+OZ_BASE    := http://localhost:8000
 
 # On a rootless Podman dev box, point Docker CLI/Compose at the Podman socket —
 # but only if that socket exists and DOCKER_HOST isn't already set, so real
@@ -19,7 +21,7 @@ export DOCKER_HOST := unix://$(PODMAN_SOCK)
 endif
 endif
 
-.PHONY: ci lint build unit smoke down changelog help
+.PHONY: ci lint build unit smoke down changelog openzaak-up openzaak-smoke openzaak-down help
 
 ## ci: run the full pipeline — lint, build, unit, smoke (mirrors Gitea Actions)
 ci: lint build unit smoke
@@ -49,6 +51,30 @@ down:
 changelog:
 	git-cliff --output CHANGELOG.md
 
+## openzaak-up: start the OpenZaak stack (migrations run on first start)
+openzaak-up:
+	docker compose -f $(OZ_COMPOSE) up -d
+
+## openzaak-smoke: start OpenZaak, then assert it is up with auth enforced
+openzaak-smoke:
+	docker compose -f $(OZ_COMPOSE) up -d
+	@bash -c 'set -e; \
+	  echo "waiting for OpenZaak to respond..."; \
+	  for i in $$(seq 1 60); do \
+	    code=$$(curl -s -o /dev/null -w "%{http_code}" $(OZ_BASE)/zaken/api/v1/zaken || true); \
+	    [ -n "$$code" ] && [ "$$code" != "000" ] && break; sleep 3; \
+	  done; \
+	  echo "GET /zaken/api/v1/zaken (unauth) -> $$code (expect 403, auth enforced)"; test "$$code" = "403"; \
+	  admin=$$(curl -s -o /dev/null -w "%{http_code}" $(OZ_BASE)/admin/); \
+	  echo "GET /admin/             -> $$admin (expect 302)"; test "$$admin" = "302"; \
+	  root=$$(curl -s -o /dev/null -w "%{http_code}" $(OZ_BASE)/zaken/api/v1/); \
+	  echo "GET /zaken/api/v1/      -> $$root (expect 200)"; test "$$root" = "200"; \
+	  echo "OpenZaak smoke OK"'
+
+## openzaak-down: stop and remove the OpenZaak stack (wipes data)
+openzaak-down:
+	docker compose -f $(OZ_COMPOSE) down --volumes
+
 ## help: list available targets
 help:
 	@grep -E '^## ' $(MAKEFILE_LIST) | sed 's/^## //'
diff --git a/docs/runbooks/openzaak.md b/docs/runbooks/openzaak.md
new file mode 100644
index 0000000..7744dc2
--- /dev/null
+++ b/docs/runbooks/openzaak.md
@@ -0,0 +1,50 @@
+# OpenZaak runbook
+
+The OpenZaak stack (`infra/openzaak/docker-compose.yml`) is a lean adaptation of the
+upstream open-zaak dev compose: PostGIS db, redis, a one-shot init that runs
+migrations, the OpenZaak API, and a celery worker.
+
+## Quick test (`make`)
+
+```bash
+make openzaak-up       # start the stack (first run pulls images + migrates: 1-3 min)
+make openzaak-smoke    # start + assert it's up with auth enforced (403/302/200)
+make openzaak-down     # stop and wipe data
+```
+
+`make openzaak-smoke` polls until the API responds, then asserts:
+
+| Check | Expected |
+|---|---|
+| `GET /zaken/api/v1/zaken` (no JWT) | **403** — `PermissionDenied` ZGW fout (auth enforced) |
+| `GET /admin/` | **302** — admin login redirect |
+| `GET /zaken/api/v1/` | **200** — ZGW API schema root |
+
+> **403, not 401.** OpenZaak's ZGW APIs return `403 PermissionDenied` for a missing
+> or invalid JWT. The S-01 acceptance text says "401" — that's inaccurate; 403 is the
+> correct auth-enforced response.
+
+The admin UI is at <http://localhost:8000/admin/>; the dev superuser is **admin /
+admin** (from the compose env — dev only).
+
+## Prerequisites (rootless Podman)
+
+Same setup as the rest of the repo (see [ci.md](ci.md)):
+
+```bash
+systemctl --user start podman.socket    # the Docker-API socket the shim talks to
+```
+
+The Makefile auto-points `DOCKER_HOST` at the Podman socket when it exists, so the
+`make openzaak-*` targets work without extra env.
+
+## Notes
+
+- **Not in `make ci`.** The OpenZaak smoke is a separate, heavier check (large image
+  pull + migrations); it is intentionally kept out of `make ci` so the core gate
+  stays fast. Run `make openzaak-smoke` when you touch the OpenZaak stack.
+- **No catalogus/zaaktypen yet.** Seeding the `BIG` catalogus + `BIG-registratie`
+  zaaktype and a JWT client is the next slice (**S-01-b**); authenticated zaaktype
+  listing isn't testable until then.
+- **Image tag.** Currently `openzaak/open-zaak:latest` via `${OPENZAAK_TAG}`; pin to
+  a known-good tag as part of the catalogus-design ADR.