Docker Health Checks
A running container does not always mean a working application. A web server can freeze, a database can lose its connections, and the process still shows as running. A health check teaches Docker to test the application itself and report its true condition.
Running vs Healthy
Consider a shop with the lights on and the door open. The shop looks open, but nobody stands behind the counter. Docker sees the lights, which is the running process. A health check walks inside and asks for a customer service reply.
Without health check: container status = Up
With health check: container status = Up (healthy)
or Up (unhealthy)
The Three Health States
starting the container just launched and checks have not passed yet healthy the latest checks succeeded unhealthy several checks in a row failed
Adding a Health Check in a Dockerfile
The HEALTHCHECK instruction defines a command that Docker runs on a schedule. A command that exits with code 0 means success. Exit code 1 means failure.
FROM nginx:alpine HEALTHCHECK --interval=30s --timeout=5s --start-period=10s --retries=3 \ CMD wget -q --spider http://localhost/ || exit 1
Understanding the Options
Option Meaning Default --------------- ---------------------------------------- ------- --interval time between checks 30s --timeout time allowed for one check 30s --start-period grace time while the app boots 0s --retries failures needed to mark unhealthy 3
The start period protects slow applications. Failures during that window do not count toward the retry limit.
Health Checks at Runtime
The docker run command can define or override a check without editing the Dockerfile.
docker run -d --name api \ --health-cmd="curl -f http://localhost:8080/health || exit 1" \ --health-interval=20s \ --health-retries=3 \ my-api
Reading Health Status
docker ps
docker inspect --format="{{.State.Health.Status}}" api
docker inspect --format="{{json .State.Health}}" api
The last command prints the recent check results, including the output and exit code of each attempt. Use it to learn why a check failed.
Writing a Good Health Endpoint
Web applications often expose a small route such as /health. A good endpoint verifies the parts the application needs.
GET /health - application process answers OK - database connection works OK - disk space is available OK Response: 200 OK
Keep the check light. A heavy check that runs every thirty seconds creates load of its own.
Health Checks in Docker Compose
services:
db:
image: postgres:16
healthcheck:
test: ["CMD-SHELL", "pg_isready -U postgres"]
interval: 10s
timeout: 5s
retries: 5
web:
image: my-web
depends_on:
db:
condition: service_healthy
The web service waits until the database reports healthy. This pattern removes the classic startup error where an application tries to connect to a database that is still loading.
What Docker Does With the Result
Plain Docker only records the status. A restart policy does not restart an unhealthy container by itself. Docker Swarm and orchestrators read the status and replace failing containers automatically. Monitoring tools can also alert you when a container turns unhealthy.
Common Mistakes
- Using a check command that does not exist inside the image, such as curl in a minimal Alpine image.
- Setting a timeout longer than the interval.
- Checking only that the port is open, which misses frozen applications.
Real-World Scenario
An online store runs a payment service in a container. One afternoon a bad database connection leaves the service stuck. The process stays alive, and Docker reports the container as Up. Customers see error pages for forty minutes before anyone notices. The team adds a health check that calls the /health route every fifteen seconds. The next time the connection breaks, the status flips to unhealthy within a minute, an alert reaches the support channel, and an engineer restarts the service before many customers feel the impact.
Choosing Check Commands for Popular Services
Service Check command ------------- ------------------------------------------ Nginx wget -q --spider http://localhost/ PostgreSQL pg_isready -U postgres MySQL mysqladmin ping -h localhost Redis redis-cli ping Node.js API node healthcheck.js
Each command exits with code 0 on success. Pick a tool that exists inside the image, because Docker runs the command inside the container itself.
Why Start Periods Matter
A Java application may need forty seconds to start. Without a start period, the first checks fail during boot and might mark a healthy application as unhealthy. Measure your real startup time and set the start period slightly above it.
