Health checks

Docker · lesson 13 of 31 · 3 min read

Tell Docker when your app is really ready, and see why unhealthy is not the same as stopped.

Open this lesson in the learning hub

Key points

  • A HEALTHCHECK runs a command inside the container on a schedule. Exit code 0 means healthy, 1 means unhealthy.
  • State goes starting, then healthy or unhealthy. --start-period stops a slow JVM boot counting as failure.
  • Docker will not restart an unhealthy container. It only reports. Compose and orchestrators are what act on it.
  • Spring Boot Actuator gives you /actuator/health, plus /actuator/health/readiness once probes are enabled.
  • Distroless images have no shell and no curl. Either add a small probe binary or run the check from Compose instead.

Example

# Dockerfile - only works on a base that actually has curl
HEALTHCHECK --interval=15s --timeout=3s --start-period=40s --retries=3 \
  CMD curl -fsS http://localhost:8080/actuator/health || exit 1

# docker ps then shows the state inline:
#   CONTAINER ID   IMAGE       STATUS
#   9f2c1a4b7d3e   myapp:1.0   Up 2 minutes (healthy)

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

Healthy means "ready for traffic". Say it explicitly or nothing can know.

Docker Compose JVM settings inside a container

This is a reading copy. The full lesson — with the visual explainer, the interactive lab and a Run button for the code — lives in the Docker course, and every lesson in it is listed on the Docker contents page.