flyer-crawler.projectium.com/docs/adr/0020-health-checks-and-liveness-readiness-probes.md

ADR-020: Health Checks and Liveness/Readiness Probes

Date: 2025-12-12

Status: Proposed

Context

When the application is containerized (ADR-014), the container orchestrator (e.g., Kubernetes, Docker Swarm) needs a way to determine if the application is running correctly. Without this, it cannot manage application lifecycle events like restarts or rolling updates effectively.

Decision

We will implement dedicated health check endpoints in the Express application.

• A Liveness Probe (/api/health/live) will return a 200 OK to indicate the server is running. If it fails, the orchestrator should restart the container.

• A Readiness Probe (/api/health/ready) will return a 200 OK only if the application is ready to accept traffic (e.g., database connection is established). If it fails, the orchestrator will temporarily remove the container from the load balancer.

Consequences

• Positive: Enables robust, automated application lifecycle management in a containerized environment. Prevents traffic from being sent to unhealthy or uninitialized application instances.
• Negative: Adds a small amount of code for the health check endpoints. Requires configuration in the container orchestration layer.