Docker Compose Healthchecks That Actually Help

Photo: Unsplash.

A process can be running while its service is unusable. A Compose healthcheck gives Docker a small, repeatable probe—but only if it checks the right thing.

For an HTTP service:

services:
  app:
    image: example/app:1.4.2
    healthcheck:
      test: ["CMD", "curl", "--fail", "--silent", "http://localhost:8080/health"]
      interval: 30s
      timeout: 5s
      retries: 3
      start_period: 20s

The command runs inside the container, so curl must exist in the image. If it does not, use a tool already present or add a tiny purpose-built probe; do not discover the missing binary during an incident.

Keep /health cheap. It should confirm that this instance can accept useful work. A deep check of every external dependency can make all app containers unhealthy during one database interruption, obscuring the real fault. Expose deeper diagnostics separately when needed.

Compose can wait for a dependency’s health during startup:

  worker:
    depends_on:
      db:
        condition: service_healthy

This improves startup ordering, but it is not runtime resilience. The worker still needs retries and sensible timeouts if the database disappears later.

Finally, an unhealthy status does not automatically restart a standalone Docker container. Orchestrators and external monitoring may act on it, but Docker Engine’s restart policy reacts to the main process exiting. Decide explicitly who observes health and what action is safe.

Test the probe manually, inspect it with docker inspect, and simulate both slow startup and dependency failure before trusting the green status.

References

• Dockerfile HEALTHCHECK
• Compose services: healthcheck