# 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-seed     # start + seed the BIG catalogus (idempotent)
make openzaak-down     # stop and wipe data
```

## Seed the BIG catalogus

`make openzaak-seed` brings the stack up and runs `infra/openzaak/seed_catalogus.py`,
which creates (idempotently, via the ZTC API):

- catalogus **BIG**
- a lean **BIG-REGISTRATIE** zaaktype (concept; only schema-mandatory fields)
- a **bsn** eigenschap on it

then confirms the JWT client can list it. See **ADR-0002** for the design (why the
zaaktype stays a concept, why notifications are disabled, why the API not a fixture).

**JWT client** (provisioned declaratively by `setup_configuration/data.yaml`, **dev only**):

| | |
|---|---|
| client_id | `big-reference-seed` |
| secret | `insecure-dev-secret-change-me` |
| authorizations | `heeft_alle_autorisaties` (all) |

The seed mints a ZGW JWT (HS256) from these and calls `/catalogi/api/v1/...`.

`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.
- **Notifications disabled.** `NOTIFICATIONS_DISABLED=true` — otherwise ZTC writes 500
  trying to notify. Open Notificaties is now up (see [opennotificaties.md](opennotificaties.md)),
  but OZ→NRC delivery wiring + re-enabling lands with **S-06**.
- **Zaaktype is a concept**, not published (publishing needs roltypen/statustypen/
  resultaattypen — beyond the lean seed). List with `?status=alles`.
- **Image tag.** Pinned to `openzaak/open-zaak:1.28.2` via `${OPENZAAK_TAG}` (bump
  deliberately, not via `:latest`).
- **Config arrives via a volume, not a bind mount.** `setup_configuration/data.yaml`
  is streamed into the external `rr-oz-config` volume by `infra/seed-config.sh`
  (`docker cp`) and mounted at `/app/setup_configuration`, so the init container
  finds it on Gitea's containerized CI runner too (bind mounts don't reach sibling
  containers there). The image is the upstream `openzaak/open-zaak` verbatim — no
  build. Run via `make openzaak-up` (seeds first). See
  [gitea-actions-gotchas.md](gitea-actions-gotchas.md).