Docker Patterns Skill

Purpose

Best practices for containerizing applications with Docker.

When to Use

Creating new Dockerfiles
Optimizing existing images
Setting up local development environments
Preparing for production deployment

Dockerfile Patterns

Multi-Stage Build (Recommended)

Separate build and runtime environments to minimize image size.

# Build stage
FROM python:3.12-slim AS builder

WORKDIR /app

# Install build dependencies
RUN apt-get update && apt-get install -y --no-install-recommends \
    build-essential \
    && rm -rf /var/lib/apt/lists/*

# Install Python dependencies
COPY requirements.txt .
RUN pip install --no-cache-dir --user -r requirements.txt

# Production stage
FROM python:3.12-slim

WORKDIR /app

# Copy only runtime dependencies
COPY --from=builder /root/.local /root/.local
ENV PATH=/root/.local/bin:$PATH

# Copy application code
COPY . .

# Run as non-root user
RUN useradd -m -r appuser && chown -R appuser:appuser /app
USER appuser

EXPOSE 8000
CMD ["uvicorn", "main:app", "--host", "0.0.0.0", "--port", "8000"]

Node.js Pattern

# Build stage
FROM node:20-alpine AS builder

WORKDIR /app

COPY package*.json ./
RUN npm ci --only=production

COPY . .
RUN npm run build

# Production stage
FROM node:20-alpine

WORKDIR /app

COPY --from=builder /app/node_modules ./node_modules
COPY --from=builder /app/dist ./dist
COPY package*.json ./

USER node

EXPOSE 3000
CMD ["node", "dist/index.js"]

Go Pattern

# Build stage
FROM golang:1.22-alpine AS builder

WORKDIR /app

COPY go.mod go.sum ./
RUN go mod download

COPY . .
RUN CGO_ENABLED=0 GOOS=linux go build -o /app/server

# Production stage - scratch for minimal size
FROM scratch

COPY --from=builder /app/server /server
COPY --from=builder /etc/ssl/certs/ca-certificates.crt /etc/ssl/certs/

EXPOSE 8080
ENTRYPOINT ["/server"]

Layer Optimization

Order by Change Frequency

Put rarely-changing layers first to maximize cache hits.

# Least frequently changed (maximize cache)
FROM python:3.12-slim
WORKDIR /app

# Dependencies change occasionally
COPY requirements.txt .
RUN pip install -r requirements.txt

# Application code changes frequently
COPY . .

CMD ["python", "main.py"]

Combine RUN Commands

Reduce layers by combining commands.

# Bad - 3 layers
RUN apt-get update
RUN apt-get install -y curl
RUN rm -rf /var/lib/apt/lists/*

# Good - 1 layer
RUN apt-get update \
    && apt-get install -y --no-install-recommends curl \
    && rm -rf /var/lib/apt/lists/*

Security Best Practices

Non-Root User

# Create and switch to non-root user
RUN useradd -m -r -s /bin/false appuser
USER appuser

Read-Only Filesystem

# docker-compose.yml
services:
  app:
    read_only: true
    tmpfs:
      - /tmp

Pin Base Image Versions

# Bad - unpredictable
FROM python:latest

# Good - reproducible
FROM python:3.12.1-slim-bookworm

Scan for Vulnerabilities

# Using Docker Scout
docker scout cves myimage:latest

# Using Trivy
trivy image myimage:latest

.dockerignore

Always include to avoid copying unnecessary files.

# Git
.git
.gitignore

# Python
__pycache__
*.pyc
*.pyo
.venv
venv

# Node
node_modules
npm-debug.log

# IDE
.vscode
.idea
*.swp

# Docker
Dockerfile*
docker-compose*
.docker

# Local config
.env
*.local

# Build artifacts
dist
build
*.egg-info

# Tests
tests
*_test.py
test_*

# Documentation
docs
*.md
!README.md

Docker Compose Patterns

Development Environment

version: '3.8'

services:
  app:
    build:
      context: .
      target: development
    volumes:
      - .:/app                    # Live reload
      - /app/node_modules         # Preserve node_modules
    environment:
      - NODE_ENV=development
      - DEBUG=true
    ports:
      - "3000:3000"
    depends_on:
      db:
        condition: service_healthy

  db:
    image: postgres:16
    environment:
      POSTGRES_USER: dev
      POSTGRES_PASSWORD: devpass
      POSTGRES_DB: devdb
    volumes:
      - postgres_data:/var/lib/postgresql/data
    healthcheck:
      test: ["CMD-SHELL", "pg_isready -U dev"]
      interval: 5s
      timeout: 5s
      retries: 5

volumes:
  postgres_data:

Production Environment

version: '3.8'

services:
  app:
    image: myregistry/myapp:${VERSION:-latest}
    deploy:
      replicas: 3
      resources:
        limits:
          cpus: '0.5'
          memory: 512M
        reservations:
          cpus: '0.25'
          memory: 256M
      restart_policy:
        condition: on-failure
        max_attempts: 3
    environment:
      - NODE_ENV=production
    healthcheck:
      test: ["CMD", "curl", "-f", "http://localhost:3000/health"]
      interval: 30s
      timeout: 10s
      retries: 3
      start_period: 40s
    logging:
      driver: json-file
      options:
        max-size: "10m"
        max-file: "3"

Health Checks

HTTP Health Check

HEALTHCHECK --interval=30s --timeout=10s --start-period=5s --retries=3 \
    CMD curl -f http://localhost:8000/health || exit 1

Custom Health Check Script

COPY healthcheck.sh /usr/local/bin/
HEALTHCHECK --interval=30s --timeout=10s --retries=3 \
    CMD healthcheck.sh

Environment Variables

Build-time vs Runtime

# Build-time arguments (not in final image)
ARG BUILD_VERSION=unknown

# Runtime environment variables
ENV APP_VERSION=${BUILD_VERSION}
ENV LOG_LEVEL=info

Using .env Files

# docker-compose.yml
services:
  app:
    env_file:
      - .env                    # Base config
      - .env.${ENV:-local}      # Environment-specific

Networking

Custom Networks

services:
  frontend:
    networks:
      - frontend
      - backend

  api:
    networks:
      - backend

  db:
    networks:
      - backend

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

Volume Patterns

Named Volumes for Persistence

volumes:
  postgres_data:
    driver: local
  redis_data:

Bind Mounts for Development

volumes:
  - ./src:/app/src:ro          # Read-only
  - ./config:/app/config       # Read-write

Common Issues & Solutions

Issue: Large Image Size

# Check what's taking space
docker history myimage:latest

# Solutions:
# - Use multi-stage builds
# - Use slim/alpine base images
# - Clean up package manager cache
# - Use .dockerignore

Issue: Slow Builds

# Solutions:
# - Optimize layer ordering
# - Use BuildKit: DOCKER_BUILDKIT=1
# - Use cache mounts for package managers
RUN --mount=type=cache,target=/root/.cache/pip \
    pip install -r requirements.txt

Issue: Container Won't Start

# Debug steps:
docker logs <container>
docker exec -it <container> /bin/sh
docker inspect <container>

Checklist

Before deploying:

docker-patterns