4.2.13 HEALTHCHECK

HEALTHCHECK is the Dockerfile instruction that defines a command Docker periodically runs inside a container to determine whether the application inside is actually functioning correctly, exposing a richer status than simply whether the container's main process is still running.

Why Process-Running Isn't Enough

A container's main process can remain running while the application itself is unresponsive — stuck, deadlocked, or unable to reach a dependency it needs. Without HEALTHCHECK, Docker has no way to distinguish a genuinely healthy container from one that is merely still alive at the process level.

HEALTHCHECK CMD curl -f http://localhost:8080/health || exit 1

This periodically checks an HTTP health endpoint, considering the container unhealthy if that endpoint does not respond successfully.

Defining a Health Check Command

The health check command should exit with status 0 if healthy, and a non-zero status if not, mirroring how Unix commands conventionally report success or failure.

HEALTHCHECK CMD curl -f http://localhost:8080/health || exit 1

Inspecting Health Status

Once configured, a container's health status becomes visible directly, distinct from whether its process is simply running.

docker ps
docker inspect myapp --format '{{.State.Health.Status}}'

docker ps reports a health status (healthy, unhealthy, or starting) directly alongside the container's running state.

Disabling an Inherited HEALTHCHECK

A base image's HEALTHCHECK can be explicitly disabled in a later stage if it is not appropriate for the final image's specific use case.

HEALTHCHECK NONE

Why HEALTHCHECK Matters

HEALTHCHECK gives orchestration tooling and monitoring systems a meaningful, application-aware signal about container health, which is essential for automated systems to make correct decisions about restarting unhealthy containers or routing traffic away from them before users are affected.