services — one container per service
yaml
services: app: build: . ports: ["127.0.0.1:3000:3000"] db: image: postgres:16-alpine
depends_on — start order
depends_on starts db before app. But started does not mean ready — Postgres needs a few seconds before accepting connections.
yaml
app: depends_on: db: condition: service_healthy
healthcheck — ready before proceeding
yaml
db: healthcheck: test: ["CMD-SHELL", "pg_isready -U knowledge_hub"] interval: 5s retries: 10
Combine depends_on with condition: service_healthy and the app only starts once the database truly accepts connections — no more "connection refused" at boot.
Rule of thumb
depends_on without a healthcheck is only a start-order hint. For a reliably booting stack, healthchecks are mandatory, not optional.