9.3.3.1 Depends Startup Order

Depends startup order is the sequence in which Compose actually starts an application's services, influenced by their declared depends_on relationships, ensuring a service's dependencies are started (and, with condition checking, properly ready) before that service itself begins starting.

How Compose Determines the Order

Compose analyzes the dependency graph formed by every service's depends_on declarations, starting services in an order that respects these relationships.

services:
  frontend:
    depends_on:
      - api
  api:
    depends_on:
      - db
  db:
    image: postgres:16

Compose starts db first, then api, then frontend, correctly respecting the chain of dependencies declared across these three services.

Why Start Order Alone Doesn't Guarantee Readiness

A dependency having started doesn't necessarily mean it's immediately ready to serve requests — without a condition-based check, a dependent service might start and attempt to connect to a dependency that's still initializing.

services:
  api:
    depends_on:
      - db
  db:
    image: postgres:16

This guarantees db's container starts before api's, but doesn't guarantee db's actual database engine is ready to accept connections by the time api starts.

Strengthening Startup Order With Health Conditions

Adding a health-based condition makes the startup order also account for actual readiness, not just container start.

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

Observing the Actual Startup Sequence

Reviewing logs across services during startup confirms the actual order things happened in, useful for verifying the configured dependency relationships are producing the intended sequence.

docker compose up

Why Depends Startup Order Matters

A correctly configured startup order, especially when strengthened with health-based conditions, is foundational to a multi-service application reliably starting up without race conditions between a service and the dependencies it actually needs to be ready.