Docker Compose for Local Development: A Complete Setup Guide

# docker-compose.yml (Docker Compose v2 - no "version:" key needed)
name: myapp

services:
  api:
    build:
      context: ./api
      target: development
      cache_from:
        - type=local,src=/tmp/.buildx-cache
    ports:
      - "3000:3000"
    volumes:
      - ./api:/usr/src/app
      - node_modules:/usr/src/app/node_modules  # Prevent host node_modules leak
    env_file:
      - .env
    environment:
      NODE_ENV: development
      DATABASE_URL: postgres://app:${POSTGRES_PASSWORD}@db:5432/myappdb
      REDIS_URL: redis://redis:6379/0
    depends_on:
      db:
        condition: service_healthy
      redis:
        condition: service_healthy
    command: npm run dev
    user: "1001:1001"   # Match your host UID to avoid root-owned volume files

  worker:
    build:
      context: ./api
      target: development
    volumes:
      - ./api:/usr/src/app
      - node_modules:/usr/src/app/node_modules
    env_file:
      - .env
    environment:
      NODE_ENV: development
      DATABASE_URL: postgres://app:${POSTGRES_PASSWORD}@db:5432/myappdb
      REDIS_URL: redis://redis:6379/0
    depends_on:
      db:
        condition: service_healthy
      redis:
        condition: service_healthy
    command: npm run worker
    user: "1001:1001"

  db:
    image: postgres:16-alpine
    restart: unless-stopped
    ports:
      - "5432:5432"
    environment:
      POSTGRES_USER: app
      POSTGRES_PASSWORD: ${POSTGRES_PASSWORD}
      POSTGRES_DB: myappdb
      POSTGRES_INITDB_ARGS: "--encoding=UTF8 --locale=en_US.UTF-8"
    volumes:
      - pgdata:/var/lib/postgresql/data
      - ./db/init.sql:/docker-entrypoint-initdb.d/10-init.sql:ro
      - ./db/seed.sql:/docker-entrypoint-initdb.d/20-seed.sql:ro
    healthcheck:
      test: ["CMD-SHELL", "pg_isready -U app -d myappdb"]
      interval: 5s
      timeout: 5s
      retries: 10
      start_period: 10s

  redis:
    image: redis:7-alpine
    restart: unless-stopped
    ports:
      - "6379:6379"
    command: >
      redis-server
      --maxmemory 256mb
      --maxmemory-policy volatile-lru
      --save ""
    healthcheck:
      test: ["CMD", "redis-cli", "ping"]
      interval: 5s
      timeout: 3s
      retries: 5

  minio:
    image: minio/minio:latest
    ports:
      - "9000:9000"
      - "9001:9001"   # MinIO Console UI
    environment:
      MINIO_ROOT_USER: ${MINIO_USER}
      MINIO_ROOT_PASSWORD: ${MINIO_PASSWORD}
    command: server /data --console-address ":9001"
    volumes:
      - minio_data:/data
    healthcheck:
      test: ["CMD", "mc", "ready", "local"]
      interval: 10s
      timeout: 5s
      retries: 3

volumes:
  pgdata:
  node_modules:
  minio_data:

# api/Dockerfile
FROM node:20-alpine AS base
WORKDIR /usr/src/app
RUN addgroup -g 1001 appgroup && adduser -u 1001 -G appgroup -s /bin/sh -D appuser

# Development stage - includes devDependencies, live reload
FROM base AS development
COPY package*.json ./
# BuildKit cache mount: npm cache persists across `docker compose build` runs
RUN --mount=type=cache,target=/root/.npm \
    npm install
COPY . .
# CMD is overridden by docker-compose.yml

# Build stage - compiles TypeScript, runs tests
FROM base AS build
COPY package*.json ./
RUN --mount=type=cache,target=/root/.npm \
    npm ci
COPY . .
RUN npm run build && npm run test:ci

# Production runtime - minimal image, no devDependencies
FROM node:20-alpine AS production
WORKDIR /usr/src/app
RUN addgroup -g 1001 appgroup && adduser -u 1001 -G appgroup -s /bin/sh -D appuser
COPY package*.json ./
RUN --mount=type=cache,target=/root/.npm \
    npm ci --omit=dev
COPY --from=build /usr/src/app/dist ./dist
USER appuser
EXPOSE 3000
CMD ["node", "dist/main.js"]

# .env.example - committed to git
POSTGRES_PASSWORD=change_me_in_env
MINIO_USER=minioadmin
MINIO_PASSWORD=change_me_in_env
REPORTER_SECRET=change_me_in_env

# .env - gitignored, copied from .env.example
POSTGRES_PASSWORD=dev_local_secret_32chars
MINIO_USER=minioadmin
MINIO_PASSWORD=dev_local_minio_secret
REPORTER_SECRET=dev_reporter_secret

secrets:
  db_password:
    file: ./secrets/db_password.txt

services:
  api:
    secrets:
      - db_password
    environment:
      DATABASE_PASSWORD_FILE: /run/secrets/db_password

# Start the entire stack (foreground - see all logs)
docker compose up

# Start detached, tail only API logs
docker compose up -d && docker compose logs -f api

# Rebuild only the api image after Dockerfile changes
docker compose up --build api

# Run a one-off command inside the running api container
docker compose exec api npm run migrate:latest

# Run a new ephemeral container (doesn't affect the running api)
docker compose run --rm api npm run db:seed

# Stop containers, preserve volumes
docker compose down

# Nuclear reset: stop, remove containers, networks, AND volumes
docker compose down -v

# View resource usage
docker compose stats

services:
  jaeger:
    image: jaegertracing/all-in-one:latest
    ports:
      - "16686:16686"
      - "4317:4317"
    profiles: ["observability"]

# Start with optional observability stack
docker compose --profile observability up

# Start without (default)
docker compose up