Docker Compose for Local Development

Docker Compose describes a multi-container setup in one file. One command starts your API, database, cache and anything else the project needs, the same way on every developer's machine.

compose.yaml

services:
  api:
    build: .
    ports:
      - "3000:3000"
    environment:
      DATABASE_URL: postgres://app:secret@db:5432/app
      REDIS_URL: redis://cache:6379
    depends_on:
      db:
        condition: service_healthy
      cache:
        condition: service_started
    develop:
      watch:
        - action: sync          # copy changed files into the container
          path: ./src
          target: /app/src
        - action: rebuild       # rebuild the image when dependencies change
          path: package-lock.json

  db:
    image: postgres:17
    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
      retries: 10

  cache:
    image: redis:8

  mailpit:
    image: axllent/mailpit
    ports: ["8025:8025"]
    profiles: ["mail"]            # only starts with --profile mail

volumes:
  pgdata:

Commands

docker compose up -d              # start everything
docker compose watch              # start and sync code changes live
docker compose logs -f api
docker compose exec db psql -U app
docker compose --profile mail up -d
docker compose down               # stop (add -v to delete volumes too)

Key ideas

• Services reach each other by service name (db, cache) on a network Compose creates.
• depends_on with service_healthy waits for the database to accept connections, not just for the container to start.
• Named volumes keep data between down and up.
• Keep secrets for real environments out of this file; use an .env file that isn't committed.