Declare a health check in the image

How to do it

Decide which check it calls, as separate alive from ready explains. Plain Docker only marks a container unhealthy, so the readiness check is safe there. Docker Swarm and some platforms replace unhealthy containers, so point it at the trivial liveness check there, or a slow database causes a restart loop. Use a one-line script in the app's language, which also works in distroless images without wget or curl. Set an interval and a start period that suit the app. Orchestrators such as Kubernetes ignore it and use their own probes, so define those there too.

Example

# Node image
HEALTHCHECK --interval=30s --start-period=10s CMD ["node", "-e", "fetch('http://localhost:8080/healthz').then(r => process.exit(r.ok ? 0 : 1), () => process.exit(1))"]

# Python image
HEALTHCHECK --interval=30s --start-period=10s CMD ["python", "-c", "import urllib.request, sys; sys.exit(0 if urllib.request.urlopen('http://localhost:8080/healthz', timeout=3).status == 200 else 1)"]

How to check

Once the start period has passed, docker inspect --format '{{.State.Health.Status}}' web prints healthy. With a readiness check, stopping the database turns it unhealthy. With a liveness check, it stays healthy.