Docker Compose depends_on ordering lacking readiness guarantee

Question

Goal: Configure a Docker Compose application so that a dependent service starts only after its prerequisite service is fully ready to accept connections.

Constraint: The depends_on directive in Compose files version 3.x guarantees only start order, not that the prerequisite has completed initialization or is listening on its ports. Health‑checks can be defined but Compose does not use them to gate the start of dependent services, leaving a gap that requires external workarounds such as retry loops or init containers.

Uncertainty: Whether a native Compose option exists to make depends_on wait for a service’s health status to become healthy, or if future versions will incorporate readiness‑based ordering without external scripting.

What configuration or flag can be added to depends_on to enforce health‑check‑based readiness?
Is there a roadmap for Compose to support conditional start ordering based on service health?
If not, what is the officially recommended pattern to achieve true readiness without compromising portability?

Tasadduq Burney · Answer

AnswerAdd a long‑form depends_on entry that specifies the service_healthy condition. This makes Compose wait until the dependency’s healthcheck reports healthy before starting the dependent service.
Confirmed facts
The Compose Specification (used by the docker compose CLI v2+) supports long‑form conditions: service_started, service_healthy, and service_completed_successfully.When condition: service_healthy is set, Compose blocks the creation of the dependent container until the referenced service’s healthcheck passes.Legacy docker‑compose binaries, Swarm stacks, and Compose file version 2.1 do not honor readiness conditions; they either ignore them or reject the file.
Steps to implement
Define a realistic healthcheck for the prerequisite service (e.g., a TCP or HTTP probe that only succeeds when the service is ready to accept traffic).Write the dependency in long form:
services:
  db:
    image: postgres:15
    healthcheck:
      test: ["CMD", "pg_isready", "-U", "${POSTGRES_USER}"]
      interval: 5s
      timeout: 2s
      retries: 5

app:
    image: myapp:latest
    depends_on:
      db:
        condition: service_healthy
    # optional: keep your own retry logic for transient connection errors

Run docker compose up (or docker compose up --wait in CI) and verify that the app container is not created until db reports healthy.
When the recommendation changesIf you are using the legacy docker‑compose binary, deploying to Swarm, or targeting an older Compose file version, the service_healthy condition will not work. In that case you must rely on external patterns such as retry loops, init containers, or docker compose up --wait for CI.
Missing diagnostic detailAre you using the standalone docker compose CLI (v2+) or the legacy docker‑compose, and are you deploying to a plain Compose project or to Swarm? This determines whether the service_healthy condition is available.

Docker Compose depends_on ordering lacking readiness guarantee

1 answer

Answer

Confirmed facts

Steps to implement

When the recommendation changes

Missing diagnostic detail

Your perspective belongs here.

0 question comments