Operator manual — request.pdhc

Day-2 operations for request.pdhc. Audience: the on-call operator.

1) Prerequisites

1.1 Software

• Docker / docker-compose v2
• PostgreSQL 16 (in container request_pdhc_db)
• Python 3.14 + the venv at gateway/venv/

1.2 Environment variables

Required in gateway/.env:

Variable	Notes
DATABASE_URL	postgresql://request:<pw>@localhost:9061/request_pdhc
FLASK_SECRET_KEY	32+ char random; never share across services
JWT_SECRET_KEY	32+ char random
SSO_BASE_URL	https://sso.pdhc.se
SSO_CLIENT_ID / SSO_CLIENT_SECRET	matched pair issued by sso.pdhc
SSO_CALLBACK_URL	https://request.pdhc.se/api/v1/auth/callback
CONTRACT_BASE_URL	http://host.docker.internal:9021
HMAC_SECRET	held only by request.pdhc (gateway delegates grant validation here)

2) Start and stop

2.1 Start

cd /usr/local/www/request.pdhc
./start.sh

Brings up request_pdhc_db on :9061 then request_pdhc_app on :9060. Health: https://request.pdhc.se/api/health returns 200 with {"status":"ok","database":"connected"}.

2.2 Stop

./stop.sh

Graceful: kill -TERM to gunicorn, wait 10s, then compose down. Database volume is preserved.

3) Backup and restore

3.1 Database backup

docker exec request_pdhc_db pg_dump -U request -F c -f /tmp/request_pdhc_$(date -u +%Y%m%dT%H%M%SZ).dump request_pdhc
docker cp request_pdhc_db:/tmp/request_pdhc_*.dump ~/backups/

3.2 Restore

docker cp ~/backups/<dump-file>.dump request_pdhc_db:/tmp/restore.dump
docker exec request_pdhc_db pg_restore -U request -d request_pdhc -c /tmp/restore.dump

Use -c for clean restore (drops + recreates objects). Drop -c to merge.

4) Common failures

4.1 Port conflicts

9060 (app) and 9061 (db) must be free before start. lsof -ti tcp:9060,9061 | xargs kill only after confirming nothing else is listening.

4.2 Database not ready

Symptom: /api/health returns 503 with database: unavailable. Causes:

• Stuck container: docker restart request_pdhc_db
• Stale colima port-forward (host can't reach container — see infra_sso_safe_restart_bug.md): colima ssh -- docker restart request_pdhc_db

4.3 SSO callback failing silently

If users land on /api/v1/auth/callback and get redirected to login again with no error, the SSO client credentials in .env are wrong. Re-check SSO_CLIENT_ID + SSO_CLIENT_SECRET against sso.pdhc's registry.

4.4 Contract validation failing

Service requests rejected with 422 / "contract not active": the contract referenced in the SR does not have Contract.status == executed. See admin-manual.md §3 for status semantics; the request fulfilment gate is not negotiable.

5) Tests

cd gateway
source venv/bin/activate
pytest -q

Endpoint smoke-test:

./scripts/test_api.sh   # if present, otherwise see api.md for a curl recipe

Results land in ./results/<timestamp>_results/.

---

For runbook-style procedures (credential rotation, incident response, upgrade) see the runbooks/ directory.