docker

name	Docker
description	Docker and container best practices — Dockerfile patterns, multi-stage builds, compose, security. Triggers on docker/container/dockerfile/compose keywords.

Docker Skill

Load this skill when working with containers, Dockerfiles, or docker-compose.

---

Rule

ALWAYS FOLLOW DOCKER BEST PRACTICES!

When creating Dockerfiles or compose files:

• Use multi-stage builds
• Run as non-root user
• Minimize image size
• Leverage layer caching

---

Dockerfile Best Practices

Multi-Stage Build

# Build stage
FROM node:20-alpine AS builder
WORKDIR /app
COPY package*.json ./
RUN npm ci --only=production

# Production stage
FROM node:20-alpine AS production
WORKDIR /app

# Create non-root user
RUN addgroup -g 1001 -S nodejs && \
    adduser -S nodejs -u 1001

# Copy only necessary files
COPY --from=builder /app/node_modules ./node_modules
COPY --chown=nodejs:nodejs . .

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

Layer Caching Order

# GOOD: Dependencies first (rarely change)
COPY package*.json ./
RUN npm ci
COPY . .

# BAD: Everything together (breaks cache)
COPY . .
RUN npm ci

Security Hardening

# Non-root user
RUN addgroup -g 1001 -S appgroup && \
    adduser -S appuser -u 1001
USER appuser

# Read-only filesystem
# Use in docker-compose: read_only: true

# No new privileges
# Use in docker-compose: security_opt: - no-new-privileges:true

# Health check
HEALTHCHECK --interval=30s --timeout=3s --start-period=5s --retries=3 \
  CMD wget --no-verbose --tries=1 --spider http://localhost:3000/health || exit 1

---

Docker Compose Patterns

Development Setup

version: '3.8'

services:
  app:
    build:
      context: .
      dockerfile: Dockerfile.dev
    volumes:
      - .:/app
      - /app/node_modules
    ports:
      - "3000:3000"
    environment:
      - NODE_ENV=development
    depends_on:
      db:
        condition: service_healthy

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

volumes:
  postgres_data:

Production Setup

version: '3.8'

services:
  app:
    image: myapp:${VERSION:-latest}
    restart: unless-stopped
    read_only: true
    security_opt:
      - no-new-privileges:true
    deploy:
      resources:
        limits:
          cpus: '1'
          memory: 512M
        reservations:
          cpus: '0.25'
          memory: 128M
    healthcheck:
      test: ["CMD", "wget", "-q", "--spider", "http://localhost:3000/health"]
      interval: 30s
      timeout: 10s
      retries: 3
      start_period: 40s
    logging:
      driver: "json-file"
      options:
        max-size: "10m"
        max-file: "3"

---

.dockerignore

# Git
.git
.gitignore

# Dependencies
node_modules
vendor

# Build artifacts
dist
build
*.log

# IDE
.idea
.vscode
*.swp

# Environment
.env
.env.*
!.env.example

# Tests
coverage
__tests__
*.test.js
*.spec.js

# Docs
README.md
docs/

# Docker
Dockerfile*
docker-compose*
.dockerignore

---

Common Commands

# Build
docker build -t myapp:latest .
docker build -t myapp:latest --target production .  # Multi-stage

# Run
docker run -d -p 3000:3000 --name myapp myapp:latest
docker run --rm -it myapp:latest sh  # Debug shell

# Compose
docker compose up -d
docker compose up -d --build  # Rebuild
docker compose down -v  # Remove volumes
docker compose logs -f app

# Debug
docker exec -it myapp sh
docker logs -f myapp
docker stats

# Cleanup
docker system prune -a  # Remove all unused
docker volume prune  # Remove unused volumes
docker image prune  # Remove dangling images

---

Image Size Optimization

Base Image	Size	Use Case
node:20	~1GB	Full features
node:20-slim	~200MB	Most apps
node:20-alpine	~130MB	Smallest
distroless/nodejs20	~120MB	Security-focused

Size Reduction Tips

1. Use Alpine-based images
2. Multi-stage builds
3. Clean package manager cache
4. Combine RUN commands
5. Remove dev dependencies

# Clean in same layer
RUN npm ci --only=production && \
    npm cache clean --force

---

Health Checks

HTTP Health Check

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

TCP Health Check

HEALTHCHECK --interval=30s --timeout=3s \
  CMD nc -z localhost 3000 || exit 1

Custom Script

COPY healthcheck.sh /usr/local/bin/
HEALTHCHECK --interval=30s CMD healthcheck.sh

---

When to Use This Skill

• Creating new Dockerfile
• Setting up docker-compose
• Optimizing image size
• Adding health checks
• Securing containers
• Debugging container issues