Phase 2 of 7

Health Checks and Resilience

Introduce lifecycle awareness, dependency sequencing, and graceful service shutdown behavior.

Overview

Replace static startup assumptions with explicit health signals. Compose should only admit dependent services when dependencies are healthy. The API should expose diagnostics strong enough for operational confidence.

What to build

Deliverables

Advance only when these outputs exist in your code or compose definitions.

  1. Implement detailed `/health` endpoint checks for DB, Redis, disk, and memory
  2. Add Docker HEALTHCHECK instructions for API and frontend
  3. Wire compose health checks for db, redis, api, and frontend
  4. Define startup order with dependent service readiness
  5. Implement graceful shutdown handling for API

Done when

Success criteria

These are acceptance indicators, not a checklist to start from.

  • Services expose and report health status
  • API waits for db and redis before serving
  • Service health transitions are visible in `docker compose ps`
  • Graceful shutdown completes cleanly under 10 seconds
  • Simulated db failures mark API as unhealthy

Verification

Testing and validation

Run these in order. Confirm each result before moving to the next step.

  1. docker compose -f docker-compose.dev.yml up

    `docker compose -f docker-compose.dev.yml up`

  2. docker compose ps

    `docker compose ps`

  3. curl http://localhost:8000/health | jq

    `curl http://localhost:8000/health | jq`

  4. docker compose pause db

    then observe API unhealthy state after 35 seconds

  5. docker compose unpause db

    and confirm recovery

  6. docker compose down

    and measure shutdown completion time