Hands-on Lab

Docker Healthchecks and Restart Policies

July 17, 2026 3 min

0 / 7

Cheat sheet

Found it useful? Don't miss the next lab

0:00 / 0:00

We bring up an nginx:alpine with a HEALTHCHECK defined straight from the command line, without touching the image. --health-cmd is what Docker runs inside the container to decide if it's healthy; --health-interval=2s sets how often the check repeats; --health-timeout=2s is the longest each attempt waits before being marked failed; --health-retries=3 is how many consecutive failures it takes to flip to unhealthy; --health-start-period=2s gives the boot some slack before failures start counting for real.

docker run -d --name web --health-cmd='wget -qO- http://localhost/ >/dev/null || exit 1' --health-interval=2s --health-timeout=2s --health-retries=3 --health-start-period=2s -p 8080:80 nginx:alpine

I did it

We check the health state with docker inspect --format, reading the container's State.Health.Status field directly. After the start period and at least one passing check, it should read 'healthy'.

sleep 5 && docker inspect --format '{{.State.Health.Status}}' web

The same information from the command we reach for daily: docker ps appends '(healthy)' to the STATUS column once a container has a HEALTHCHECK defined and passing. Two different commands, same confirmation that web is healthy.

docker ps --filter name=web --format 'table {{.Names}}\t{{.Status}}'

We force an unhealthy state on purpose: --health-cmd points at port 9999, where nginx isn't listening, so wget will always fail. With health-retries=2 and a 1s start-period it only takes a few seconds to flip to unhealthy, so we see it right away.

docker run -d --name web-bad --health-cmd='wget -qO- http://localhost:9999/ >/dev/null || exit 1' --health-interval=2s --health-timeout=2s --health-retries=2 --health-start-period=1s nginx:alpine

I did it

We confirm with docker inspect and docker ps that web-bad settled into unhealthy once its retries ran out: Docker doesn't restart it on its own, or stop it; it just flags it for you (or an orchestrator) to act on.

sleep 7 && docker inspect --format '{{.State.Health.Status}}' web-bad && docker ps -a --filter name=web-bad --format 'table {{.Names}}\t{{.Status}}'

In Compose, the healthcheck is written as a YAML mapping (test/interval/timeout/retries/start_period) instead of flags, meaning the same thing as on docker run. The key part is app: depends_on.cache.condition: service_healthy, which blocks app from starting until cache reports healthy, something a plain, order-only depends_on doesn't give you.

mkdir -p /root/lab && cat > /root/lab/compose.yaml <<'YAML'
services:
  cache:
    image: redis:alpine
    healthcheck:
      test: ['CMD', 'redis-cli', 'ping']
      interval: 2s
      timeout: 2s
      retries: 3
      start_period: 2s
    restart: unless-stopped
  app:
    image: alpine:3.20
    command: ['sh', '-c', 'echo App container starting now that cache is healthy; sleep 3600']
    depends_on:
      cache:
        condition: service_healthy
    restart: unless-stopped
YAML
cd /root/lab && docker compose up -d

I did it

docker compose ps shows cache as '(healthy)' and app as Up; its logs already contain the startup message, proof that Compose held app back until cache passed its healthcheck, not before.

cd /root/lab && sleep 6 && docker compose ps && echo '--- app logs ---' && docker compose logs app --no-color --tail=5

We bring up a container whose main process always exits 1, with --restart on-failure:5: Docker restarts it automatically on every failure, with a growing backoff between attempts, up to a cap of 5 times. on-failure only fires on an error exit; an exit 0 or a docker stop never triggers it.

docker run -d --name flaky --restart on-failure:5 alpine:3.20 sh -c 'echo crashing on purpose; exit 1'

I did it

docker inspect exposes RestartCount: a counter Docker bumps every time it restarts the container. Seeing it above zero, alongside Status, confirms on-failure genuinely did its job, not just on paper.

sleep 10 && docker inspect --format 'RestartCount={{.RestartCount}} Status={{.State.Status}}' flaky

We bring up a container with --restart unless-stopped to contrast it with always: both survive a crash or a daemon restart, but only unless-stopped makes an exception when it's you who stops the container.

docker run -d --name sticky --restart unless-stopped redis:alpine

I did it

We confirm sticky is Up before touching it, so the next step, stopping it by hand, is a clean comparison.

docker ps --filter name=sticky --format 'table {{.Names}}\t{{.Status}}'

We stop it ourselves, on purpose, with docker stop. This is a manual user action, not a process failure: the unless-stopped policy treats this case differently from a crash.

docker stop sticky

I did it

sticky stays Exited: unless-stopped honors the manual docker stop and doesn't bring it back. With --restart always, on the other hand, Docker would have started it right back up without being asked.

sleep 3 && docker ps -a --filter name=sticky --format 'table {{.Names}}\t{{.Status}}'

We tear down the Compose stack (containers, network, and volume) and remove the four standalone containers we created during the lab, so nothing keeps running on the throwaway host.

cd /root/lab && docker compose down --remove-orphans -v && docker rm -f web web-bad flaky sticky

I did it

We close by checking that no container is left: the list is empty and the final count is 0, proof the lab leaves the host exactly as it found it.

docker ps -a --format '{{.Names}}'; echo "remaining containers: $(docker ps -aq | wc -l)"

Was this lab useful? Rate it:

Click to rate this post!

[Total: 0 Average: 0]

Docker healthchecks and restart policies solve a problem a plain docker ps can’t see: a process staying alive doesn’t mean it’s actually serving anything useful. A web server can hang without crashing, and without a HEALTHCHECK, Docker has no way to know.

From starting to healthy or unhealthy

A HEALTHCHECK is defined with –health-cmd on docker run, or with the healthcheck field in a compose.yaml, and it uses four parameters: the interval between checks, the maximum time per attempt, the number of consecutive failures needed to flip to unhealthy, and a start period during which failures don’t count yet. docker inspect –format ‘{{.State.Health.Status}}’ and the STATUS column of docker ps surface that state at any moment.

Restarts: no, on-failure, always, and unless-stopped

The restart policy (–restart) is independent from the healthcheck: it decides what Docker does when the container’s main process exits. on-failure:N only kicks in on a non-zero exit code and accepts a retry cap; always and unless-stopped also restart after a daemon restart, but unless-stopped honors a manual docker stop and won’t bring the container back until you decide to.

service_healthy in Compose

Combining both pieces, depends_on: condition: service_healthy in Compose delays a service’s startup until its dependency’s healthcheck reports healthy, something a plain depends_on, which only orders containers, cannot guarantee. It’s the same idea we covered while building healthchecks and restart policies in Docker Compose, applied here with real commands against a real Docker daemon.

If you’re coming from Docker fundamentals, this lab pairs with what we covered in volumes and bind mounts and Docker networking, and with the rest of our Tools guides. The official reference for the instruction lives in the Docker documentation, the open specification for Compose’s healthcheck field is in the Compose Specification repository, and the command we use to check Redis is documented in the Redis reference.

FAQ

What is a Docker HEALTHCHECK?

It's a command Docker runs inside the container itself at a fixed interval (–health-interval, or the healthcheck field in Compose) to decide whether the process is genuinely serving, not just still running. If the command fails health-retries times in a row, Docker marks the container unhealthy, without restarting it on its own.

What is the difference between the on-failure, always, and unless-stopped restart policies?

on-failure only restarts the container when its main process exits with a non-zero code, and accepts a cap like on-failure:5. always restarts it no matter what, even after a manual docker stop or a daemon restart, unless you remove the container. unless-stopped behaves like always, but it honors an explicit docker stop: it won't bring the container back until you start it yourself or Docker restarts.

How does Compose use depends_on: condition: service_healthy?

With that setting, Compose won't start the dependent service until the healthcheck of the service it depends on reports healthy, not merely once that container exists. Without condition: service_healthy, depends_on only orders container startup, with no guarantee the first one is actually ready to take traffic.

Cheat sheet

docker run -d --name web --health-cmd='wget -qO- http://localhost/ >/dev/null || exit 1' --health-interval=2s --health-timeout=2s --health-retries=3 --health-start-period=2s -p 8080:80 nginx:alpine

docker run -d --name web-bad --health-cmd='wget -qO- http://localhost:9999/ >/dev/null || exit 1' --health-interval=2s --health-timeout=2s --health-retries=2 --health-start-period=1s nginx:alpine

mkdir -p /root/lab && cat > /root/lab/compose.yaml <<'YAML'
services:
  cache:
    image: redis:alpine
    healthcheck:
      test: ['CMD', 'redis-cli', 'ping']
      interval: 2s
      timeout: 2s
      retries: 3
      start_period: 2s
    restart: unless-stopped
  app:
    image: alpine:3.20
    command: ['sh', '-c', 'echo App container starting now that cache is healthy; sleep 3600']
    depends_on:
      cache:
        condition: service_healthy
    restart: unless-stopped
YAML
cd /root/lab && docker compose up -d

docker run -d --name flaky --restart on-failure:5 alpine:3.20 sh -c 'echo crashing on purpose; exit 1'

docker run -d --name sticky --restart unless-stopped redis:alpine

```
docker stop sticky
```

cd /root/lab && docker compose down --remove-orphans -v && docker rm -f web web-bad flaky sticky

Found it useful? Don't miss the next lab

Subscribe to the newsletter

From starting to healthy or unhealthy

Restarts: no, on-failure, always, and unless-stopped

service_healthy in Compose

FAQ

What is a Docker HEALTHCHECK?

What is the difference between the on-failure, always, and unless-stopped restart policies?

How does Compose use depends_on: condition: service_healthy?

Cheat sheet