Docker in Dev vs Prod

# syntax=docker/dockerfile:1
FROM node:18-alpine AS base
# Stage 1 — shared foundation
# Everything both dev and prod need in common goes here.
WORKDIR /app
COPY package*.json ./

# ────────────────────────────────────────────────────────
FROM base AS development
# Stage 2 — development image
# npm install with ALL dependencies including devDependencies.
RUN npm install
# Source code is NOT copied here — it will be mounted as a volume
# so that edits on the host appear instantly inside the container.
EXPOSE 3000
CMD ["npm", "run", "dev"]
# npm run dev = nodemon or equivalent — watches for file changes and restarts

# ────────────────────────────────────────────────────────
FROM base AS production
# Stage 3 — production image
# Install production dependencies only — no test runners, no build tools.
RUN npm install --omit=dev
# Copy source code into the image — immutable from this point forward.
COPY . .
# Non-root user — security hardening from Lesson 32.
RUN addgroup -S appgroup && \
    adduser -S appuser -G appgroup && \
    chown -R appuser:appgroup /app
USER appuser
EXPOSE 3000
CMD ["node", "server.js"]
# node directly — no file watcher, no dev tooling, no restarter.

# Build the development image — targets the "development" stage
docker build --target development -t payment-api:dev .

# Build the production image — targets the "production" stage
docker build --target production -t payment-api:prod .

# The production image contains only production dependencies and compiled code.
# The development image contains devDependencies and no source code.
# Same Dockerfile. Same source. Completely different outputs.

# docker-compose.yml — base, shared across all environments
version: "3.8"

services:
  api:
    build:
      context: .
      dockerfile: Dockerfile
    depends_on:
      - db

  db:
    image: postgres:15-alpine
    volumes:
      - pgdata:/var/lib/postgresql/data

volumes:
  pgdata:

# docker-compose.dev.yml — development overrides
version: "3.8"

services:
  api:
    build:
      target: development
      # Build the development stage — includes devDependencies
    volumes:
      - .:/app
      # Mount the entire project into /app — edits appear instantly
      - /app/node_modules
      # Anonymous volume prevents the host node_modules from
      # overwriting the container's node_modules
    ports:
      - "3000:3000"
      - "9229:9229"
      # 9229 is the Node.js debugger port — exposed for IDE attachment
    environment:
      - NODE_ENV=development
      - LOG_LEVEL=debug
    env_file:
      - .env.development
      # Local .env file with dummy credentials — safe to have on disk

  db:
    ports:
      - "5432:5432"
      # Expose Postgres locally so developers can connect with pgAdmin or psql

# docker-compose.prod.yml — production overrides
version: "3.8"

services:
  api:
    build:
      target: production
      # Build the production stage — hardened, minimal, non-root
    image: acmecorp/payment-api:${GIT_SHA}
      # Use the pre-built registry image — never build on the production server
    ports:
      - "3000:3000"
      # Only the application port — no debugger, no database port
    environment:
      - NODE_ENV=production
      - LOG_LEVEL=info
    env_file:
      - .env.production
    deploy:
      resources:
        limits:
          cpus: "1.5"
          memory: 512M
        reservations:
          cpus: "0.5"
          memory: 256M
    restart: unless-stopped
    logging:
      driver: json-file
      options:
        max-size: "10m"
        max-file: "5"
    read_only: true
    # Read-only root filesystem — from Lesson 32

# Running each environment — the -f flag stacks the files
# Development:
docker compose -f docker-compose.yml -f docker-compose.dev.yml up

# Production:
docker compose -f docker-compose.yml -f docker-compose.prod.yml up -d

# The second file's values override the first file's values where they conflict.
# Keys that only exist in the base file are inherited unchanged.
# Keys that only exist in the override file are added.

# File structure:
# ├── Dockerfile                  ← multi-stage: dev + prod stages
# ├── docker-compose.yml          ← base: shared service definitions
# ├── docker-compose.dev.yml      ← dev overrides: volumes, ports, hot-reload
# ├── docker-compose.prod.yml     ← prod overrides: limits, logging, read-only
# ├── .env.development            ← dummy credentials — safe, committed
# ├── .env.production             ← real credentials — on server, gitignored
# └── .gitignore
#     .env.production
#     .env*.local

# Developer workflow — on their laptop:
git clone git@github.com:acmecorp/payment-api.git
cd payment-api
docker compose -f docker-compose.yml -f docker-compose.dev.yml up
# → Hot-reload running. Edit code. Changes live in <1s. No rebuild.

# CI pipeline — on every merge to main:
docker build --target production -t acmecorp/payment-api:${GIT_SHA} .
docker push acmecorp/payment-api:${GIT_SHA}
# → Production image built, tested, pushed to registry.

# Production server — deploy:
GIT_SHA=a3f2c8d docker compose \
  -f docker-compose.yml \
  -f docker-compose.prod.yml \
  up -d
# → Pulls the tested image from registry. No git. No build. No source code on server.