Docker Restart Policies Without the Magic

Photo: Unsplash.

A restart policy is useful, but it is not a health check, a dependency manager, or proof that an application is ready. It answers a narrower question: what should Docker do after this container stops?

The four common policies are:

• no: do not restart automatically; this is the default.
• on-failure[:max-retries]: restart only after a non-zero exit code, optionally with a retry limit.
• always: restart after any exit; a manual stop suppresses restarts until the daemon restarts or the container is started again.
• unless-stopped: behave like always, but preserve an intentional stopped state across daemon restarts.

For a small long-running service, unless-stopped is often the least surprising choice:

docker run -d \
  --name example-api \
  --restart unless-stopped \
  example/api:1.4.2

The Compose equivalent is:

services:
  api:
    image: example/api:1.4.2
    restart: unless-stopped

For a batch job that should expose its failure instead of retrying forever, use on-failure with a bound:

docker run --restart on-failure:3 example/importer:1.4.2

Inspect the loop before changing it

If a container keeps restarting, read its state and logs rather than repeatedly calling docker restart:

docker inspect -f '{{.State.Status}} {{.State.ExitCode}} {{.RestartCount}}' example-api
docker logs --tail 100 --timestamps example-api

A process exiting because configuration is missing will not become healthy through persistence. An unlimited restart policy can instead turn one clear failure into noisy logs and repeated load.

Also separate restart policies from Docker’s live-restore feature. Restart policies act after containers stop. Live restore is about keeping Linux containers running while the Docker daemon is unavailable during certain outages or upgrades.

Use the policy to express expected lifecycle, then use application health checks, monitoring, and tested shutdown behavior for the rest. A restart is recovery only when the next start has a realistic chance of succeeding.

Reference

• Docker Docs: Start containers automatically