Docker Compose

# Verify V2 plugin (note: no hyphen)
docker compose version

# V1 still on PATH? Uninstall or alias away
which docker-compose  # should be empty or a warning wrapper

name: order-platform

services:
  api:
    image: ghcr.io/acme/api:${API_TAG:-latest}
    ports:
      - "${API_PORT:-8080}:8080"
    environment:
      DATABASE_URL: postgres://app:${DB_PASSWORD}@db:5432/orders
    depends_on:
      db:
        condition: service_healthy
    networks:
      - frontend
      - backend

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

networks:
  frontend:
  backend:
    internal: true

volumes:
  pgdata:

services:
  api:
    build:
      context: ./services/api          # directory sent as build context
      dockerfile: Dockerfile.prod    # relative to context
      args:
        NODE_ENV: development
        APP_VERSION: ${GIT_SHA:-dev}
      target: runtime                # multi-stage: stop at this stage
    image: acme/api:${GIT_SHA:-dev}

services:
  api:
    depends_on:
      db:
        condition: service_healthy
      redis:
        condition: service_started   # no healthcheck defined

  db:
    healthcheck:
      test: ["CMD-SHELL", "pg_isready -U $$POSTGRES_USER"]
      interval: 5s
      retries: 10
      start_period: 30s

services:
  worker:
    image: acme/worker:2.1.0
    deploy:
      replicas: 2
      resources:
        limits:
          cpus: "0.50"
          memory: 512M
        reservations:
          memory: 256M
      restart_policy:
        condition: on-failure
        max_attempts: 3

# Start core stack only
docker compose up -d

# Add observability and mail catcher
docker compose --profile observability --profile devtools up -d

services:
  prometheus:
    image: prom/prometheus:v2.52.0
    profiles: [observability]

  mailhog:
    image: mailhog/mailhog
    profiles: [devtools]

deploy/
├── compose.yaml           # shared services, networks, volumes
├── compose.override.yaml  # auto-loaded locally (gitignored or committed)
├── compose.prod.yaml      # prod: image tags, limits, no bind mounts
├── .env.example           # documented defaults (committed)
└── .env                   # local secrets (gitignored)

name: order-platform

services:
  api:
    image: ghcr.io/acme/api:${API_TAG:-latest}
    environment:
      LOG_LEVEL: ${LOG_LEVEL:-info}
      DATABASE_URL: postgres://app:${DB_PASSWORD}@db:5432/orders
    depends_on:
      db:
        condition: service_healthy
    networks: [app]

  db:
    image: postgres:16-alpine
    environment:
      POSTGRES_USER: app
      POSTGRES_PASSWORD: ${DB_PASSWORD}
      POSTGRES_DB: orders
    volumes:
      - pgdata:/var/lib/postgresql/data
    healthcheck:
      test: ["CMD-SHELL", "pg_isready -U app -d orders"]
      interval: 5s
      retries: 5
    networks: [app]

networks:
  app:

volumes:
  pgdata:

services:
  api:
    build:
      context: ../services/api
      target: dev
    ports:
      - "127.0.0.1:8080:8080"
    volumes:
      - ../services/api/src:/app/src:cached
    environment:
      LOG_LEVEL: debug
      DEBUG: "true"

services:
  api:
    image: ghcr.io/acme/api:${API_TAG}   # required in prod — no default
    restart: unless-stopped
    ports:
      - "443:8080"
    deploy:
      resources:
        limits:
          memory: 1G
          cpus: "1.0"
    logging:
      driver: json-file
      options:
        max-size: "10m"
        max-file: "5"

  db:
    restart: unless-stopped
    # no host port publish — DB reachable only on app network

docker compose \
  -f compose.yaml \
  -f compose.prod.yaml \
  --env-file .env.prod \
  up -d

# .env.example — commit this
API_TAG=latest
API_PORT=8080
LOG_LEVEL=info
DB_PASSWORD=change-me-local

# .env — gitignore; copy from example
DB_PASSWORD=dev-secret-42

services:
  api:
    build:
      context: ./api
      target: dev
    command: npm run dev
    volumes:
      - ./api/src:/app/src:cached
      - ./api/package.json:/app/package.json:ro
    environment:
      NODE_ENV: development
      CHOKIDAR_USEPOLLING: "true"   # file watch on Docker Desktop VM

services:
  api:
    ports:
      - "8080:8080"
      - "9229:9229"   # Node inspector
    command: node --inspect=0.0.0.0:9229 src/index.js

  # Java example
  billing:
    ports:
      - "5005:5005"
    environment:
      JAVA_TOOL_OPTIONS: "-agentlib:jdwp=transport=dt_socket,server=y,suspend=n,address=*:5005"

services:
  db:
    image: postgres:16-alpine
    environment:
      POSTGRES_USER: app
      POSTGRES_PASSWORD: dev
      POSTGRES_DB: orders
    volumes:
      - pgdata:/var/lib/postgresql/data
      - ./db/init:/docker-entrypoint-initdb.d:ro   # 01-schema.sql, 02-seed.sql

volumes:
  pgdata:

name: shop-local

services:
  api:
    build:
      context: ./api
      target: dev
    ports:
      - "127.0.0.1:3000:3000"
    volumes:
      - ./api:/app:cached
    environment:
      REDIS_URL: redis://cache:6379
      DATABASE_URL: postgres://app:dev@db:5432/shop
    depends_on:
      db:
        condition: service_healthy
      cache:
        condition: service_started
    networks: [frontend, backend]

  db:
    image: postgres:16-alpine
    environment:
      POSTGRES_USER: app
      POSTGRES_PASSWORD: dev
      POSTGRES_DB: shop
    volumes:
      - pgdata:/var/lib/postgresql/data
      - ./db/init:/docker-entrypoint-initdb.d:ro
    healthcheck:
      test: ["CMD-SHELL", "pg_isready -U app -d shop"]
      interval: 3s
      retries: 10
    networks: [backend]

  cache:
    image: redis:7-alpine
    networks: [backend]

  worker:
    build:
      context: ./worker
    command: npm run jobs:dev
    volumes:
      - ./worker:/app:cached
    environment:
      REDIS_URL: redis://cache:6379
    depends_on: [cache]
    networks: [backend]
    profiles: [jobs]

networks:
  frontend:
  backend:

volumes:
  pgdata:

services:
  api:
    build: ./api
    develop:
      watch:
        - path: ./api/src
          action: sync
          target: /app/src
        - path: ./api/package.json
          action: rebuild

docker compose watch
# or
docker compose up --watch

# From api container — DNS resolves "db"
docker compose exec api getent hosts db

# Inspect the project network
docker network inspect shop-local_backend

services:
  gateway:
    image: nginx:alpine
    ports:
      - "80:80"
    networks: [frontend]

  api:
    image: acme/api:1.4.0
    networks: [frontend, backend]

  db:
    image: postgres:16-alpine
    networks: [backend]

networks:
  frontend:
    driver: bridge
  backend:
    driver: bridge
    internal: true

# Create once on the host
docker network create proxy

# compose.yaml references it

services:
  api:
    image: acme/api:1.4.0
    networks:
      - default
      - proxy

networks:
  proxy:
    external: true
    name: proxy

docker compose config          # validate YAML + env
docker compose pull            # refresh base images
docker compose up -d --build   # build local services, start detached
docker compose ps              # health status
docker compose logs -f api     # tail one service
docker compose exec db psql -U app -d orders
docker compose run --rm api npm test
docker compose down            # stop; add -v to wipe named volumes

name: order-platform-prod

services:
  api:
    image: ghcr.io/acme/api@sha256:abc123...   # immutable digest
    restart: unless-stopped
    ports:
      - "443:8080"
    environment:
      DATABASE_URL: postgres://app@db:5432/orders
      LOG_LEVEL: info
    secrets:
      - db_password
    depends_on:
      db:
        condition: service_healthy
    deploy:
      resources:
        limits:
          cpus: "2.0"
          memory: 2G
    healthcheck:
      test: ["CMD", "curl", "-f", "http://localhost:8080/health"]
      interval: 30s
      timeout: 5s
      retries: 3
      start_period: 60s
    logging:
      driver: json-file
      options:
        max-size: "25m"
        max-file: "10"
    networks: [edge, data]

  db:
    image: postgres:16-alpine
    restart: unless-stopped
    environment:
      POSTGRES_USER: app
      POSTGRES_PASSWORD_FILE: /run/secrets/db_password
      POSTGRES_DB: orders
    secrets:
      - db_password
    volumes:
      - pgdata:/var/lib/postgresql/data
    healthcheck:
      test: ["CMD-SHELL", "pg_isready -U app -d orders"]
      interval: 10s
      retries: 5
    deploy:
      resources:
        limits:
          memory: 4G
    logging:
      driver: json-file
      options:
        max-size: "10m"
        max-file: "5"
    networks: [data]

secrets:
  db_password:
    file: ./secrets/db_password.txt   # chmod 600; not in git

networks:
  edge:
  data:
    internal: true

volumes:
  pgdata:
    driver: local

# On production host
export API_TAG=sha256:abc123...
docker compose -f compose.yaml -f compose.prod.yaml pull
docker compose -f compose.yaml -f compose.prod.yaml up -d --remove-orphans
docker compose ps