Master Docker’s Native Health Checks: From Dockerfile to Compose

Docker Native Health Check Capability

Since version 1.12 Docker includes a native health‑check mechanism. The simplest check verifies that the PID 1 process is alive, but more complex issues like application deadlocks require custom health‑check commands. Containers start in the starting state, then Docker runs the health‑check command at the configured interval. A non‑zero exit code or a timeout marks the check as failed; after retries consecutive failures the container becomes unhealthy.

Note: A single successful check restores the healthy state, and Docker emits a health_status event whenever the health status changes.

1. Dockerfile Method

You can declare a health‑check directly in the Dockerfile using the HEALTHCHECK instruction. HEALTHCHECK [options] CMD <command>: set the command to run. HEALTHCHECK NONE: disable any inherited health‑check.

Note: Only one HEALTHCHECK line is allowed per Dockerfile; later lines overwrite earlier ones.

The instruction supports options such as: --interval=<time>: interval between checks (default 30s). --timeout=<time>: maximum time a check may run (default 30s). --retries=<count>: number of consecutive failures before marking unhealthy (default 3). --start-period=<time>: grace period after container start during which failures are ignored (default 0s).

Example Dockerfile for a simple web service:

FROM nginx:1.23
HEALTHCHECK --interval=5s --timeout=3s --retries=3 \
    CMD curl -fs http://localhost/ || exit 1

Build and run the image:

docker build -t myweb:v1 .

docker run -d --name web myweb:v1

After a few seconds the container status changes from (health: starting) to (healthy). If the health‑check fails repeatedly, the status becomes (unhealthy). The health‑check output is stored in the container’s state and can be inspected with:

docker inspect --format '{{json .State.Health}}' web | python -m json.tool

2. docker run Method

You can also specify health‑check options directly in the docker run command:

docker run -d \
    --name=myweb \
    --health-cmd="curl -fs http://localhost/ || exit 1" \
    --health-interval=5s \
    --health-retries=12 \
    --health-timeout=2s \
    nginx:1.23

Relevant flags include --health-cmd, --health-interval, --health-retries, --health-start-period, --health-timeout, and --no-healthcheck to disable any Dockerfile‑defined checks.

3. docker‑compose Method

In a docker‑compose.yml file you can define a health‑check under the service definition:

version: '3'
services:
  web:
    image: nginx:v1
    container_name: web
    healthcheck:
      test: ["CMD", "supervisorctl", "status"]
      interval: 5s
      timeout: 2s
      retries: 3

After bringing the stack up, the container will show Up (healthy). If a sub‑service managed by supervisorctl stops, the health‑check will eventually mark the container as unhealthy.