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.