Startup order and healthchecks

The core idea

depends_on tells Compose to start one service before another. On its own, it only waits until the dependency's container has started, not until the program inside is ready. Add condition: service_healthy and a healthcheck, and Compose waits until the dependency reports healthy.

Started is not ready

Postgres takes a few seconds after its container starts before it accepts connections. With plain depends_on, the API can start in that gap and fail its first connection:

api:
  depends_on: [db, cache]    # waits for the containers to start, nothing more

Waiting for healthy

Give each dependency a healthcheck, then depend on its health:

api:
  depends_on:
    db:
      condition: service_healthy
    cache:
      condition: service_healthy

db:
  image: postgres:18
  healthcheck:
    test: ["CMD-SHELL", "pg_isready -U $${POSTGRES_USER} -d $${POSTGRES_DB}"]
    interval: 5s
    timeout: 3s
    retries: 10

cache:
  image: redis:8-alpine
  healthcheck:
    test: ["CMD", "redis-cli", "ping"]
    interval: 5s
    timeout: 3s
    retries: 5

Both images ship a client that can check readiness: pg_isready and redis-cli ping. Now up waits:

$ docker compose up -d
Container notes-db-1 Started
Container notes-cache-1 Started
Container notes-db-1 Waiting
Container notes-cache-1 Waiting
Container notes-cache-1 Healthy
Container notes-db-1 Healthy
Container notes-api-1 Starting
Container notes-api-1 Started
Container notes-api-1 Waiting
Container notes-api-1 Healthy
Container notes-proxy-1 Starting
Container notes-proxy-1 Started

Output trimmed. The API starts only after both dependencies are healthy, and the proxy only after the API is, because the full file also gives api a healthcheck and makes proxy depend on it.

Two details in that healthcheck

• CMD vs CMD-SHELL. CMD runs a program directly, like exec-form CMD in a Dockerfile. CMD-SHELL runs the string through /bin/sh, which you need for $VARIABLES.
• $$. Compose replaces ${VAR} in the file with values from your environment before anything runs. $$ escapes that, so $${POSTGRES_USER} reaches the container as ${POSTGRES_USER} and the shell inside the container expands it from the container's environment.

The three conditions

That's why the notes API keeps its own retry loop even though Compose now orders startup. Ordering makes the happy path clean; retries make the unhappy path survivable.

Recap

Interview questions