Compose

Everything so far has been one container at a time, typed by hand. A real application is four containers with a network, two volumes, an ordering constraint, and eleven flags nobody will remember tomorrow.

Compose is that written down. One file, one command, reproducible.

The file

compose.yaml in your project root:

services:
  api:
    build: .
    ports:
      - "3000:3000"
    environment:
      DATABASE_URL: postgres://app:secret@db:5432/app
    depends_on:
      db:
        condition: service_healthy

  db:
    image: postgres:17-alpine
    environment:
      POSTGRES_USER: app
      POSTGRES_PASSWORD: secret
      POSTGRES_DB: app
    volumes:
      - pgdata:/var/lib/postgresql/data
    healthcheck:
      test: ["CMD-SHELL", "pg_isready -U app"]
      interval: 5s
      timeout: 3s
      retries: 5

volumes:
  pgdata:

Read what it did without being asked. It created a network — a user-defined one, so api can reach db by name, which is the DNS problem from the last lesson solved by default. It created the volume. It waited for Postgres to report healthy before starting the API. Four things you would otherwise have typed, in order, correctly, every time.

There is no version: key

If you have seen Compose files before, you have seen this at the top:

version: "3.8"     # obsolete — delete it

Do not write it. That key belonged to Compose v1's file-format versioning, which was retired years ago. The current Compose Specification has no version field; the file format is versionless and features are detected from what you actually use. Modern Compose ignores the key, and older versions of Compose v2 warn about it.

Its presence in a tutorial is the most reliable single indicator that the tutorial predates roughly everything in this course.

The commands worth knowing

docker compose up -d              # create/start everything, detached
docker compose down               # stop and remove containers + network
docker compose down -v            # ...and delete the volumes. Careful.
docker compose ps                 # what is running
docker compose logs -f api        # follow one service
docker compose exec api sh        # shell into a running service
docker compose run --rm api npm test   # one-off container, then delete it
docker compose build              # rebuild images
docker compose pull               # refresh images from the registry

The two that get mixed up are exec and run. exec needs the service already running and joins it. run starts a new container from the same definition — useful for tests, migrations, and shells against a service that is currently crashing.

And down -v deletes your named volumes. Plain down does not. That one flag is the difference between "stop the stack" and "stop the stack and destroy the database".

depends_on and what it actually promises

depends_on:
  - db

This controls start order only. Compose starts db first, then immediately starts api — it does not wait for Postgres to be ready to accept connections, because it has no way of knowing what "ready" means. Your API tries to connect a hundred milliseconds later and crashes.

The long form fixes it, and requires the dependency to declare a healthcheck:

depends_on:
  db:
    condition: service_healthy

Three conditions are available: service_started (the old behaviour), service_healthy (waits for the healthcheck to pass), and service_completed_successfully (waits for a one-shot container to exit 0 — migrations, seed jobs).

Next up: the last lesson — finding out what went wrong, and stopping Docker from filling your disk.