9.3.3.2 Depends Service Declaration

Depends service declaration is the act of explicitly naming, within a service's depends_on field, exactly which other services within the same Compose file it relies on, making an application's internal dependency relationships clearly visible directly within its own definition.

Declaring Dependencies Explicitly

Each dependency relationship is declared by listing the relevant service's name under the dependent service's depends_on field.

services:
  api:
    depends_on:
      - db
      - cache
  db:
    image: postgres:16
  cache:
    image: redis:7

Why Explicit Declaration Is Valuable Beyond Just Startup Ordering

Beyond influencing startup order, an explicit depends_on declaration documents an application's actual internal architecture directly within the Compose file itself, making these relationships clear to anyone reading the file without needing to infer them from application code or separate documentation.

services:
  frontend:
    depends_on:
      - api
  api:
    depends_on:
      - db
      - cache
  worker:
    depends_on:
      - db
      - queue

Reading through these declarations alone reveals a fairly complete picture of how this application's services relate to one another.

A Dependency Not Requiring a Network Connection Doesn't Need Declaration

depends_on specifically expresses a startup-order (and optionally readiness) relationship — a service that merely shares a network with another, without genuinely needing it to be ready first, doesn't necessarily need an explicit depends_on entry just for that shared network connectivity.

services:
  monitoring:
    networks:
      - app-net

This service shares a network without necessarily declaring a depends_on relationship, if it doesn't actually require another specific service to be ready first.

Why Depends Service Declaration Matters

Thoughtfully and accurately declaring depends_on relationships throughout a Compose file both ensures a sound startup sequence and provides valuable, self-documenting insight into how an application's various services actually relate to and rely upon one another.