Docker and Docker Compose command reference

Building and moving images

Gotcha: layer cache invalidation is ordered. Copy the lockfile and install dependencies before copying the rest of the source, or every source edit reinstalls the whole dependency tree.

Volumes, networks, and reclaiming disk

Gotcha: named volumes survive docker rm and even docker compose down. They do not survive --volumes on either command. Never add that flag to a script that runs unattended.

Reference files worth copying

A Compose file with the parts people forget

name: myapp

services:
  api:
    build:
      context: .
      target: runner
      args:
        NODE_VERSION: "22"
    ports:
      - "3000:3000"
    env_file: [.env]
    environment:
      DATABASE_URL: postgres://postgres:secret@db:5432/app
    depends_on:
      db:
        condition: service_healthy
    healthcheck:
      test: ["CMD", "curl", "-fsS", "http://localhost:3000/healthz"]
      interval: 10s
      timeout: 3s
      retries: 5
      start_period: 20s
    restart: unless-stopped
    develop:
      watch:
        - action: sync
          path: ./src
          target: /app/src
        - action: rebuild
          path: package.json

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

volumes:
  pgdata:

Gotcha: the top level version: key is obsolete in Compose v2 and prints a warning. Delete it. Plain depends_on only waits for the container to start, not for the service to be usable, which is why the condition form above matters.

A multi stage Node Dockerfile

FROM node:22-alpine AS deps
WORKDIR /app
COPY package.json package-lock.json ./
RUN npm ci --omit=dev

FROM node:22-alpine AS builder
WORKDIR /app
COPY --from=deps /app/node_modules ./node_modules
COPY . .
RUN npm run build

FROM node:22-alpine AS runner
WORKDIR /app
ENV NODE_ENV=production
COPY --from=deps /app/node_modules ./node_modules
COPY --from=builder /app/dist ./dist
USER node
EXPOSE 3000
CMD ["node", "dist/server.js"]

Gotcha: use the exec form CMD ["node", "x.js"], not the shell form. The shell form wraps your process in /bin/sh -c, so it never receives SIGTERM and every stop takes the full ten second timeout. Also add a .dockerignore containing at least node_modules, .git, and dist.