How do Docker health checks work and why are they important?

Question

Accepted Answer

A **health check** tells Docker (or an orchestrator) how to determine whether a container's application is actually **working**, not just running. A container's process can be up while the app is broken (hung, can't reach its database) — health checks detect this so the platform can react.

## Defining a health check

```dockerfile
# in a Dockerfile
HEALTHCHECK --interval=30s --timeout=3s --retries=3 \
  CMD curl -f http://localhost:3000/health || exit 1
# → Docker runs this command periodically; exit 0 = healthy, non-zero = unhealthy
```

```yaml
# in docker-compose.yml
healthcheck:
  test: ["CMD", "curl", "-f", "http://localhost:3000/health"]
  interval: 30s
  timeout: 3s
  retries: 3
  start_period: 10s    # grace period on startup before failures count
```

Docker periodically runs the health-check command; the container's status becomes `healthy` or `unhealthy` based on the result (visible in `docker ps`).

## Running vs healthy (the key distinction)

```text
RUNNING → the container's process is alive (but the APP might be hung/broken)
HEALTHY → the health check confirms the app actually WORKS (responds correctly)
→ A container can be RUNNING but NOT HEALTHY (e.g. the app deadlocked, lost its DB).
  Without a health check, the platform only knows "running" — and keeps sending traffic
  to a broken container.
```

## Why health checks matter operationally

```text
✓ ORCHESTRATORS use them: restart unhealthy containers; route traffic only to healthy ones
✓ Compose depends_on: condition: service_healthy → wait for real readiness
✓ LIVENESS (is it alive? restart if not) vs READINESS (ready for traffic? hold traffic if not)
  → Kubernetes uses liveness + readiness probes (the same concept, more granular)
✓ Prevents serving requests from broken-but-running containers
```

## Why it matters

Understanding Docker health checks is important for **running reliable containerized applications**, so it's valuable operational knowledge.

The crucial insight is the distinction between **running and healthy**: a container's process can be **alive while the application is actually broken** (hung, deadlocked, unable to reach its database) — and without a health check, the platform only knows the container is "running" and will **keep routing traffic to a broken container**, causing failures.

Health checks solve this by defining how to verify the application **actually works** (e.g. hitting a `/health` endpoint), so the container's status reflects real health, not just process liveness.

This matters **operationally** because orchestrators and tools act on it: they **restart unhealthy containers** (automatic recovery from hangs/deadlocks) and **route traffic only to healthy ones** (avoiding sending requests to broken instances), and Compose's `depends_on: condition: service_healthy` uses health checks to wait for genuine readiness (solving startup races).

Understanding the related **liveness vs readiness** distinction (is it alive and should be restarted, vs is it ready to receive traffic) is important, as **Kubernetes uses liveness and readiness probes** built on this same concept — so understanding Docker health checks transfers directly to orchestrated environments.

Since reliable operation requires distinguishing "running" from "actually working" and reacting to broken-but-running containers (restarting them, withholding traffic), and since health checks are the mechanism enabling this — used by orchestrators for self-healing and traffic routing — understanding Docker health checks is valuable, practically-important knowledge for running containers reliably, a key practice for production resilience that prevents the common problem of broken containers silently continuing to receive traffic, and a concept foundational to how orchestrators maintain application health.