Service Dependencies and Startup Order

web needs db to be up before it can serve a request, so the instinct is depends_on: [db] and assume the problem is solved. It is not. Plain depends_on waits only for the db container to start — not for Postgres inside it to finish initializing and start accepting connections — so web races ahead, connects to a port that isn't listening yet, and crashes on boot.

This is the single most common Compose footgun, and it trips everyone exactly once. The fix is small once you see it, but the failure mode is confusing because every service reports "running" while the stack is plainly broken.

What depends_on Actually Guarantees

depends_on in its short form orders container start: on up, Compose starts the dependencies first and the dependents after. That is the entire promise. "Started" means the container process is running — the kernel has launched the entrypoint — not that the application inside has finished booting and is ready to serve. The ordering is real and useful; the readiness guarantee people expect is not there.

Started Is Not Ready

postgres:16 spends a few seconds after its container starts initializing the data directory, running startup scripts, and finally binding port 5432. During that window the container is "running" but Postgres is not yet listening. web, having been told only to start after db started, opens its connection in exactly that window, gets connection-refused, and exits. The stack appears broken on first up even though every service is "running" — which is precisely why the cause is hard to spot.

Healthchecks Plus condition: service_healthy

The correct fix is to gate on readiness, not on start. Give db a healthcheck that probes whether Postgres actually accepts connections — pg_isready is the standard probe — and change web's dependency to the long form with condition: service_healthy. Now Compose holds web back until db's healthcheck passes, which is the moment Postgres is truly listening. This is the same HEALTHCHECK mechanism the image chapters touched, and Chapter 11 topic 67 covers how the check itself is written and tuned.

services:
  web:
    build: ./web
    image: driftwood/web
    depends_on:
      db:
        condition: service_healthy
    networks:
      - driftwood-net

  db:
    image: postgres:16
    healthcheck:
      test: ["CMD-SHELL", "pg_isready -U driftwood -d driftwood"]
      interval: 5s
      timeout: 3s
      retries: 5
    volumes:
      - driftwood-db-data:/var/lib/postgresql/data
    networks:
      - driftwood-net

  proxy:
    image: nginx:1.27-alpine
    depends_on:
      web:
        condition: service_started
    ports:
      - "80:80"
      - "443:443"
    networks:
      - driftwood-net

Read the dependency chain off the file: proxy waits for web to start, web waits for db to pass pg_isready. The healthcheck retries every five seconds up to five times, so Compose holds web for as long as Postgres needs to come up and no longer.

App-Side Retry as the Resilient Path

Health gating fixes cold boot, but it does not cover a dependency that restarts mid-life. If db is restarted for an upgrade while web is running, the healthcheck condition was satisfied long ago and does nothing now — web simply loses its connection. The durable answer is for the application itself to retry the database connection with backoff, both at startup and on any dropped connection. The healthcheck handles the cold-boot half; the retry handles everything after.

Driftwood Wired Correctly

In the finished file db carries a pg_isready-based healthcheck, web depends on db with condition: service_healthy, and proxy depends on web. The chain means a single docker compose up brings the stack up in an order where each tier finds the one below it actually listening — no race, no connection-refused, no manual sleep between commands. Driftwood's own startup code also retries its connection, so a later db restart no longer takes web down with it.