9.3.3.3 Depends Health Conditions

Depends health conditions are the condition: service_healthy form of a depends_on declaration, instructing Compose to wait for a dependency's own health check to report a healthy status before starting the dependent service, providing a meaningfully stronger readiness guarantee than waiting for the dependency to simply start.

Configuring a Health Condition

This requires both a health check defined on the dependency and a corresponding condition declared on the dependent service.

services:
  api:
    depends_on:
      db:
        condition: service_healthy
  db:
    image: postgres:16
    healthcheck:
      test: ["CMD-SHELL", "pg_isready -U postgres"]
      interval: 5s
      timeout: 5s
      retries: 5

Compose starts api only once db's health check has reported healthy, not merely once db's container has started.

Why This Provides a Stronger Guarantee Than Plain Depends On

A database container can be running for some time before its actual database engine finishes initializing and is ready to accept connections — a plain depends_on without a health condition can't distinguish between these two states, while a properly configured health check can.

docker compose up -d
docker compose ps

Reviewing service status reveals whether db is merely "running" or has actually reached a "healthy" state, the distinction this condition relies on.

Designing an Appropriate Health Check for This Purpose

The health check itself needs to accurately reflect genuine readiness — a check that merely confirms the process is running, without confirming it can actually serve requests, wouldn't provide the stronger guarantee this condition is meant to offer.

healthcheck:
  test: ["CMD", "curl", "-f", "http://localhost:8080/health"]
  interval: 10s
  retries: 3

Why Depends Health Conditions Matter

Using health-based conditions for genuinely critical startup dependencies provides considerably more reliable coordination than relying on container start order alone, meaningfully reducing the chance of a dependent service failing its first interactions with a dependency that's technically running but not yet actually ready.