Docker Compose — depends_on Basics

The depends_on key tells Compose to start services in order. It does NOT wait for the dependency to be “ready” — only started.

Basic Usage

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

Compose starts db and cache first, then api.

What depends_on Does and Doesn’t Do

Feature	depends_on (basic)
Start order	✓ Controlled
Wait for container start	✓ Yes
Wait for app readiness	✗ No
Stop order	✓ Reverse of start

The Problem

Timeline:
  0s   db container starts
  1s   api container starts      ← depends_on triggers this
  3s   PostgreSQL ready           ← but postgres isn't ready yet!
  1-3s api crashes (connection refused)

The container is “started” but the application inside (PostgreSQL) is still initializing.

Startup vs Shutdown

depends_on also controls shutdown order — reverse of startup:

Startup:  db → cache → api
Shutdown: api → cache → db

docker compose up -d    # Starts: db, cache, api
docker compose down     # Stops:  api, cache, db

Dependency Chain

services:
  web:
    depends_on: [api]
  api:
    depends_on: [db, cache]
  db:
    image: postgres:16
  cache:
    image: redis:7

Resolved start order: db + cache → api → web

Summary

Aspect	Detail
Purpose	Control start/stop order
Syntax	depends_on: [svc1, svc2]
Waits for	Container start (not app readiness)
Stop order	Reverse of start
For readiness	Use health checks + condition:

---

Quick Reference

Item	Detail
depends_on	Controls service start order
Does NOT	Wait for application readiness
Stop order	Reverse of startup order
Chains	Transitive dependencies resolved
Readiness	Requires health check + condition