feat(health): M5-03 — /ready readiness probe, compose healthcheck gate

[bihius]

Summary

• Adds GET /ready — a real readiness probe that checks DB connectivity (SELECT 1) and whether the runtime config volume is a writable directory. Returns 200 with per-check status when healthy, 503 with a detailed breakdown when any dependency is unavailable.
• Keeps GET /health as a pure liveness probe (static 200, no dependencies checked).
• Switches the Docker Compose backend healthcheck from /health → /ready so the five dependent services (frontend, haproxy, coraza, log-shipper) only start once the backend can actually serve traffic.
• Fixes a silent bug: GUARD_PROXY_RUNTIME_DIR in compose was never read by the Python settings layer (field is RUNTIME_GENERATED_CONFIG_ROOT). Renamed to match; value is unchanged.

What changed and why

File	Change
src/backend/app/main.py	New readiness_check endpoint; extends _HealthcheckAccessFilter to also suppress GET /ready poll noise; updated imports
deploy/docker/docker-compose.yml	Healthcheck URL /health → /ready; env var rename fix
tests/integration/test_health_router.py	7 new tests: liveness 200, readiness 200 (happy path), 503 on DB failure, 503 on missing config dir, 503 when both fail, auth-not-required for both
tests/unit/test_access_logging.py	2 new tests for the updated filter
README.architecture.md	New "Health and Readiness Probes" section with endpoint table and response shape examples
README.md	Access table updated with separate liveness/readiness rows

Response shape

// GET /ready → 200
{"status": "ready", "checks": {"database": {"status": "ok"}, "runtime_config": {"status": "ok"}}}

// GET /ready → 503 (one check failed)
{"status": "not ready", "checks": {"database": {"status": "ok"}, "runtime_config": {"status": "error", "detail": "/var/lib/guard-proxy/generated is not a writable directory"}}}

Test plan

• uv run python -m pytest tests/unit/test_access_logging.py tests/integration/test_health_router.py -v — 12/12 passed
• Full compose stack: make run → confirm backend reaches healthy state and all dependents start
• Manual: curl -i localhost:8080/health (200), curl -i localhost:8080/ready (200)

Closes #128

[Copilot]

Pull request overview

Adds a real readiness probe to the FastAPI backend and wires Docker Compose health checks to gate dependent services on actual backend readiness (DB + runtime config volume), while keeping /health as a lightweight liveness endpoint.

Changes:

• Added GET /ready readiness probe (DB SELECT 1 + runtime generated config directory is writable) and updated access-log filtering to suppress probe noise.
• Updated Compose backend healthcheck to call /ready and fixed the runtime config env var name to match the backend settings field.
• Added integration/unit tests for the probes and logging filter; updated README docs to document both endpoints.

Reviewed changes

Copilot reviewed 6 out of 6 changed files in this pull request and generated 2 comments.

Show a summary per file

File	Description
src/backend/app/main.py	Implements /ready readiness probe and suppresses access logs for /ready polling.
deploy/docker/docker-compose.yml	Switches healthcheck endpoint to /ready and renames env var to RUNTIME_GENERATED_CONFIG_ROOT.
src/backend/tests/integration/test_health_router.py	Adds integration coverage for /health and /ready success/failure scenarios.
src/backend/tests/unit/test_access_logging.py	Extends unit coverage for access-log filter to include /ready.
README.architecture.md	Documents liveness vs readiness probes, response shape, and Compose gating behaviour.
README.md	Updates quickstart access table to list both probes.