Docker health checks let the platform actively verify a container is genuinely functioning correctly — not just running, but actually healthy — enabling better restart behavior and dependency management.
Running vs Healthy: An Important Distinction
A container can be "running" (the process hasn't crashed) while the application inside is completely unresponsive or malfunctioning — health checks let Docker distinguish between merely running and genuinely healthy.
Defining a Health Check in Docker Compose
services:
app:
image: myapp
healthcheck:
test: ["CMD", "curl", "-f", "http://localhost:3000/health"]
interval: 30s
timeout: 5s
retries: 3
start_period: 10s| Parameter | Meaning |
|---|---|
| interval | How often to run the check |
| timeout | Maximum time the check itself can take before being considered failed |
| retries | Consecutive failures before marking the container unhealthy |
| start_period | Grace period after startup before failures count toward the retry threshold |
Adding a Health Check Endpoint to Your Application
See How to Add Health Check Endpoints to Your Application — your application needs a lightweight endpoint (often /health) that verifies genuine functional health (can it reach its database, are core dependencies working), not just that the HTTP server itself is responding.
Health Checks for Databases
services:
db:
image: postgres:16
healthcheck:
test: ["CMD-SHELL", "pg_isready -U postgres"]
interval: 10s
timeout: 5s
retries: 5Health Checks for Redis
services:
redis:
image: redis:7
healthcheck:
test: ["CMD", "redis-cli", "ping"]
interval: 10sChecking Health Status
docker psShows health status (healthy/unhealthy/starting) directly in the status column for containers with configured health checks.
Using Health Checks with depends_on
services:
app:
depends_on:
db:
condition: service_healthy
db:
image: postgres:16
healthcheck:
test: ["CMD-SHELL", "pg_isready -U postgres"]Ensures app only starts after db is genuinely healthy (not just running), avoiding a common race condition where an application starts before its database is actually ready to accept connections.
Combining with Restart Policies
See Docker Restart Policies and Healthchecks Explained — an unhealthy container (based on health check status) can trigger automatic restart behavior depending on your configured restart policy, providing automated recovery from certain failure modes.
Choosing a Meaningful Health Check
Avoid overly shallow checks that only verify the process is running — a genuinely useful health check verifies actual functional capability (can it serve a real request, reach its dependencies) rather than just process existence.
Common Errors
Container marked unhealthy despite seemingly working fine — verify the health check command itself is correctly written and actually reachable from within the container (e.g. curl must be installed in the image if your check uses it).
Continue Reading
- How to Add Health Check Endpoints to Your Application
- Docker Restart Policies and Healthchecks Explained
- How to Set Up Basic Load Balancing with Nginx
Browse more articles in Docker & Containers.
