Docker Containerization Skill

Comprehensive guide for Docker containerization: Dockerfiles, multi-stage builds, Docker Compose orchestration, development environments, and advanced patterns.

When to Use / Not Use

Use when:

• Writing or optimizing Dockerfiles (multi-stage builds, layer caching, image size)
• Setting up Docker Compose for multi-container apps (health checks, volumes, networks)
• Creating isolated development environments with worktrees
• Configuring DDEV for PHP/TYPO3 projects
• Managing ports, browser isolation, and CORS in multi-worktree setups
• Running container optimization analysis (scripts/docker_optimize.py)

Do NOT use when:

• CI/CD pipeline YAML or pipeline configuration -> use cicd-pipelines
• Workflow orchestration or release automation -> use workflow-automation
• Kubernetes or container orchestration platforms -> use cloud-native tooling
• Debugging containerized applications -> use debugging (but this skill helps with environment setup)

Decision Tree

What Docker task do you need?
├── Write a Dockerfile
│   ├── Single-language app, no build step -> Single-stage FROM + COPY + CMD
│   ├── Compiled/bundled app (TypeScript, Go, wheel) -> Multi-stage build (build + production)
│   ├── Need smallest image -> Alpine or distroless base, multi-stage
│   └── PHP/TYPO3 project -> DDEV (see references/ddev-quickstart.md)
├── Set up Docker Compose
│   ├── Single app + DB -> 2 services, health check on DB, depends_on with condition
│   ├── Multiple services (app + DB + cache + worker) -> Named volumes, health checks, resource limits
│   ├── Need worktree isolation -> Port ranges per worktree, prefixed container names
│   └── Environment-specific configs -> Override files: docker-compose.override.yml
├── Optimize existing image
│   ├── Image too large -> Run docker_optimize.py, add .dockerignore, reorder layers
│   ├── Build too slow -> Reorder: COPY deps first, RUN install, then COPY source
│   └── Security issues -> Non-root user, specific version tags, no build tools in production
├── Development environment
│   ├── Git worktree isolation -> references/docker-worktree-strategy.md + worktree-manager.sh
│   ├── Browser isolation for E2E -> references/browser-isolation.md + setup-mcp-isolation.sh
│   └── Port conflicts -> references/port-allocation.md (systematic ranges)
└── Troubleshooting
    ├── Build fails -> Check Dockerfile syntax, cache, .dockerignore
    ├── Container can't connect -> Check network, service names, health checks
    ├── Data lost on restart -> Use named volumes (not anonymous/binds)
    └── DDEV issues -> references/ddev-troubleshooting.md

Quick Start

Basic Docker Workflow

# Create Dockerfile
cat > Dockerfile <<EOF
FROM node:20-alpine
WORKDIR /app
COPY package*.json ./
RUN npm ci --production
COPY . .
EXPOSE 3000
USER node
CMD ["node", "server.js"]
EOF

# Build and run
docker build -t myapp:1.0 .
docker run -d -p 3000:3000 --name myapp myapp:1.0

See: references/docker-basics.md

Docker Compose Multi-Container App

# docker-compose.yml
version: '3.8'
services:
  web:
    build: .
    ports:
      - "3000:3000"
    depends_on:
      db:
        condition: service_healthy
      redis:
        condition: service_healthy
    environment:
      - DATABASE_URL=postgresql://user:***@db:5432/app

  db:
    image: postgres:15-alpine
    volumes:
      - postgres_data:/var/lib/postgresql/data
    healthcheck:
      test: ["CMD", "pg_isready", "-U", "user"]
      interval: 5s
      retries: 5

  redis:
    image: redis:7-alpine
    healthcheck:
      test: ["CMD", "redis-cli", "ping"]
      interval: 5s
      retries: 5

volumes:
  postgres_data:

See: references/docker-compose.md

Core Docker Concepts

Dockerfile Best Practices

# Use specific versions (not latest)
FROM node:20.11.0-alpine3.19

# Set working directory
WORKDIR /app

# Copy dependency files first (better caching)
COPY package*.json ./
RUN npm ci --only=production

# Copy application code
COPY . .

# Set environment variables
ENV NODE_ENV=production

# Document exposed ports
EXPOSE 3000

# Create and use non-root user (security)
RUN addgroup -g 1001 -S nodejs && \
    adduser -S nodejs -u 1001
USER nodejs

# Default command
CMD ["node", "server.js"]

Multi-Stage Builds

# Stage 1: Build
FROM node:20-alpine AS build
WORKDIR /app
COPY package*.json ./
RUN npm ci
COPY . .
RUN npm run build

# Stage 2: Production (smaller image)
FROM node:20-alpine
WORKDIR /app
COPY --from=build /app/dist ./dist
COPY --from=build /app/node_modules ./node_modules
USER node
EXPOSE 3000
CMD ["node", "dist/server.js"]

Benefits: Smaller images, improved security, no build tools in production.

.dockerignore

node_modules
.git
.env
*.log
.DS_Store
README.md
docker-compose.yml
dist
coverage

Anti-Patterns

Best Practices

Dockerfiles

• Use specific image versions, not latest
• Run as non-root user
• Multi-stage builds to minimize size
• Implement health checks
• Set resource limits
• Keep images under 500MB
• Scan for vulnerabilities regularly

Docker Compose

• Use named volumes for data persistence
• Implement health checks for all services
• Set restart policies for production
• Use environment-specific compose files
• Configure resource limits
• Enable logging with size limits
• Network isolation with custom networks

Development Environments

• Use consistent port allocation across worktrees
• Isolate browser state for parallel testing
• Copy .env files when creating worktrees
• Configure CORS for worktree frontend ports
• Stop services when not in use

Quick Reference

Scripts Reference

Reference Navigation

Resources

• Docker Docs: https://docs.docker.com
• Docker Compose: https://docs.docker.com/compose/
• Dockerfile Reference: https://docs.docker.com/engine/reference/builder/
• DDEV: https://ddev.readthedocs.io/
• Docker Security: https://docs.docker.com/engine/security/

Integration

• cicd-pipelines -- Build and deploy Docker images this skill creates
• workflow-automation -- Automate deployment workflows using Docker containers
• debugging -- Debug containerized applications and CI/CD failures
• testing-framework -- Set up testing infrastructure inside containers