Add /healthz endpoint for container healthcheck #26

New issue

Open

opened 2026-04-19 11:08:13 -06:00 by claude-code · 0 comments

claude-code commented

2026-04-19 11:08:13 -06:00

Collaborator

Part of the platform-contract intake (#25).

The Archon platform contract requires every long-running container to declare a Docker HEALTHCHECK. cAdvisor exports container_health_status to Prometheus; absent health checks show as "none" and cannot drive the container-down alert planned for launch (5.4 in #25).

Scope

Add GET /healthz to the FastAPI app.
Return 200 on success, 503 when the check fails.
Success condition: app is up and the DB is reachable. A trivial SELECT 1 via the SQLAlchemy session is enough; the SQLite file is the only data store.
No auth. The Traefik basic-auth middleware will protect the rest of the app, but the healthcheck must remain unauthenticated so the Docker HEALTHCHECK (running inside the container) and any infra probes can hit it.

Out of scope

/readyz / /livez split. One endpoint is enough for a single-container app with no warm-up phase.
Application-level metrics (/metrics) — not on the launch list (5.2 in #25).

Deliverables

Route handler + tests.
HEALTHCHECK directive in the eventual Dockerfile / Compose service once the deploy scaffolding lands.

Tracks work that blocks first deploy per #25.

Part of the platform-contract intake (#25). The Archon platform contract requires every long-running container to declare a Docker `HEALTHCHECK`. cAdvisor exports `container_health_status` to Prometheus; absent health checks show as "none" and cannot drive the container-down alert planned for launch (5.4 in #25). ## Scope - Add `GET /healthz` to the FastAPI app. - Return `200` on success, `503` when the check fails. - Success condition: app is up **and** the DB is reachable. A trivial `SELECT 1` via the SQLAlchemy session is enough; the SQLite file is the only data store. - No auth. The Traefik basic-auth middleware will protect the rest of the app, but the healthcheck must remain unauthenticated so the Docker `HEALTHCHECK` (running inside the container) and any infra probes can hit it. ## Out of scope - `/readyz` / `/livez` split. One endpoint is enough for a single-container app with no warm-up phase. - Application-level metrics (`/metrics`) — not on the launch list (5.2 in #25). ## Deliverables - Route handler + tests. - `HEALTHCHECK` directive in the eventual `Dockerfile` / Compose service once the deploy scaffolding lands. Tracks work that blocks first deploy per #25.