Docker Compose Cheat Sheet: Services, Volumes, Networks & Production Patterns

Quick reference tables

Core CLI commands

Service inspection

Executing commands in containers

Service definition fields

Environment variables

Volumes

Top-level volumes block (required for named volumes):

volumes:
  pgdata:          # Docker-managed named volume
  uploads:
    driver: local  # Explicit driver (default)

Networks

Top-level networks block:

networks:
  frontend:
  backend:
    internal: true  # No external internet access

Health checks

Detailed sections

Minimal production compose file

A realistic three-tier app: Node.js API, PostgreSQL database, Nginx reverse proxy. Replace values as needed.

services:
  db:
    image: postgres:16-alpine
    restart: unless-stopped
    environment:
      POSTGRES_USER: ${DB_USER}
      POSTGRES_PASSWORD: ${DB_PASSWORD}
      POSTGRES_DB: ${DB_NAME}
    volumes:
      - pgdata:/var/lib/postgresql/data
    healthcheck:
      test: ["CMD-SHELL", "pg_isready -U ${DB_USER}"]
      interval: 10s
      timeout: 5s
      retries: 5
    networks:
      - backend

  api:
    build:
      context: ./api
      dockerfile: Dockerfile
    restart: unless-stopped
    environment:
      DATABASE_URL: postgres://${DB_USER}:${DB_PASSWORD}@db:5432/${DB_NAME}
      NODE_ENV: production
    depends_on:
      db:
        condition: service_healthy
    networks:
      - backend
      - frontend

  nginx:
    image: nginx:alpine
    restart: unless-stopped
    ports:
      - "80:80"
      - "443:443"
    volumes:
      - ./nginx/nginx.conf:/etc/nginx/nginx.conf:ro
      - ./certs:/etc/ssl:ro
    depends_on:
      - api
    networks:
      - frontend

volumes:
  pgdata:

networks:
  frontend:
  backend:
    internal: true

Key points in this config:

• The database is on backend only — it’s not reachable from the host or from Nginx directly
• The API is on both networks — it can reach the database and be reached by Nginx
• service_healthy means the API won’t start until Postgres is actually accepting connections
• The internal: true backend network has no internet routing — containers on it cannot initiate outbound connections

Override files for dev vs. production

The standard pattern: docker-compose.yml is the base, docker-compose.override.yml adds dev-specific config that is automatically merged.

# docker-compose.override.yml (dev only, NOT committed if it has secrets)
services:
  api:
    build:
      target: development      # Multi-stage: use dev stage
    volumes:
      - ./api:/app             # Live code reload
    environment:
      NODE_ENV: development
      DEBUG: "app:*"
    ports:
      - "9229:9229"            # Node.js debugger port

  db:
    ports:
      - "5432:5432"            # Expose DB port locally for psql/DBeaver

For production, pass the prod override explicitly:

docker compose -f docker-compose.yml -f docker-compose.prod.yml up -d

The -f flag stops the automatic override merge, so only the files you list are used.

Environment variable precedence (highest to lowest)

1. Values set with --env-file on the CLI
2. Shell environment variables exported in the current session
3. .env file in the project directory
4. environment: block in docker-compose.yml
5. Default values from the image ENV layer

Practical consequence: if NODE_ENV=production is in your shell, it overrides whatever is in the .env file. This is often surprising on CI servers where the shell environment already has values set by the CI platform.

Multi-stage builds with compose

For APIs or apps that have both a dev and prod image from the same Dockerfile:

# Dockerfile
FROM node:22-alpine AS base
WORKDIR /app
COPY package*.json ./
RUN npm ci

FROM base AS development
RUN npm install --include=dev
CMD ["npm", "run", "dev"]

FROM base AS production
COPY . .
RUN npm run build
CMD ["node", "dist/server.js"]

# docker-compose.yml (production target)
services:
  api:
    build:
      context: .
      target: production

# docker-compose.override.yml (development target, no target = dev)
services:
  api:
    build:
      target: development
    volumes:
      - .:/app
      - /app/node_modules  # Anonymous volume so host node_modules don't override

The anonymous volume trick (/app/node_modules) is important: without it, the bind mount would overwrite the container’s node_modules with whatever (or nothing) is in your host directory.

Profiles — optional services

Profiles let you define services that only start when you specifically request them. Common uses: development databases, mock servers, test utilities, admin UIs.

services:
  api:
    build: .
    # No profile — always starts

  db:
    image: postgres:16-alpine
    # No profile — always starts

  adminer:
    image: adminer
    ports:
      - "8080:8080"
    profiles:
      - dev       # Only starts with: docker compose --profile dev up

  redis:
    image: redis:alpine
    profiles:
      - dev
      - cache

# Start base services only
docker compose up -d

# Start base + dev profile services
docker compose --profile dev up -d

# Start base + both profiles
docker compose --profile dev --profile cache up -d

Scaling services

# Run 3 replicas of the worker service
docker compose up -d --scale worker=3

For this to work cleanly, the scaled service must not use container_name (would conflict) and must not bind a host port directly. Use a load balancer (Nginx, Traefik) in front of it instead.

Cleaning up

# Remove stopped containers
docker compose rm

# Remove containers and volumes (database data included)
docker compose down -v

# Remove all unused containers, networks, images (not just compose)
docker system prune -f

# Nuclear option: also remove volumes
docker system prune -f --volumes

Related: Docker Cheat Sheet | Nginx Cheat Sheet | How to Write a Node.js Dockerfile

System_Continuity

Next_Recommended_Node

jq Cheat Sheet: Filter, Transform, and Query JSON from the Terminal

Complete jq reference — basic filters, pipes, array/object operations, conditionals, string interpolation, select, map, reduce, and real DevOps workflows.

Cobie

5m read

Cheatsheet 5m

Nginx Cheat Sheet: Config, Routing, SSL & Performance

Log_Access

Cheatsheet 5m

Docker Cheat Sheet: Images, Containers, Compose & More

Log_Access

Browse the full manifest