docker / health-check

docker HEALTHCHECK — add container health check

Quick Answer

# Dockerfile
HEALTHCHECK --interval=30s --timeout=5s --start-period=10s --retries=3 \
  CMD curl -f http://localhost:3000/health || exit 1

Usage

You want Docker (or an orchestrator like Compose/Kubernetes) to detect when a container is no longer serving traffic correctly.

Other causes & fixes

HEALTHCHECK options explained

HEALTHCHECK \
  --interval=30s   \ # how often to check (default 30s)
  --timeout=5s     \ # time limit per check (default 30s)
  --start-period=10s \ # grace period after start (default 0s)
  --retries=3      \ # failures before "unhealthy" (default 3)
  CMD curl -f http://localhost/health || exit 1

Check health status

docker inspect --format '{{.State.Health.Status}}' my-container
# healthy | unhealthy | starting

# Show last few health log entries
docker inspect --format '{{range .State.Health.Log}}{{.Output}}{{end}}' my-container

Docker Compose healthcheck

# docker-compose.yml
services:
  app:
    image: my-app
    healthcheck:
      test: ["CMD", "curl", "-f", "http://localhost:3000/health"]
      interval: 30s
      timeout: 5s
      retries: 3
      start_period: 10s

Disable an inherited healthcheck

# In a child image or Compose override
HEALTHCHECK NONE

Related