docker-best-practices

OverviewHistoryStatsSecurity

npx skills add ...

Documentation

SKILL.md

Comprehensive Docker best practices for images, containers, and production deployments. PROACTIVELY activate for: (1) writing production-ready Dockerfiles, (2) multi-stage builds for lean images, (3) base image selection (distroless, alpine, scratch, slim), (4) layer caching and ordering, (5) .dockerignore hygiene, (6) HEALTHCHECK and graceful shutdown, (7) non-root user and least-privilege patterns, (8) ENV vs ARG and secret handling, (9) tag/digest pinning and reproducibility, (10) Compose for local development. Provides: Dockerfile templates by language, image-size optimization checklist, .dockerignore template, HEALTHCHECK patterns, and Compose dev-stack examples.

npx skills add josiahsiegel/claude-plugin-marketplace --skill docker-best-practices

Documentation

SKILL.mdView source

🚨 CRITICAL GUIDELINES

Windows File Path Requirements

MANDATORY: Always Use Backslashes on Windows for File Paths

When using Edit or Write tools on Windows, you MUST use backslashes (\) in file paths, NOT forward slashes (/).

Examples:

❌ WRONG: D:/repos/project/file.tsx
✅ CORRECT: D:\repos\project\file.tsx

This applies to:

Edit tool file_path parameter
Write tool file_path parameter
All file operations on Windows systems

Documentation Guidelines

NEVER create new documentation files unless explicitly requested by the user.

Priority: Update existing README.md files rather than creating new documentation
Repository cleanliness: Keep repository root clean - only README.md unless user requests otherwise
Style: Documentation should be concise, direct, and professional - avoid AI-generated tone
User preference: Only create additional .md files when user specifically asks for documentation

Docker Best Practices

This skill provides current Docker best practices across all aspects of container development, deployment, and operation.

Image Best Practices

Base Image Selection

2025 Recommended Hierarchy:

Wolfi/Chainguard (cgr.dev/chainguard/*) - Zero-CVE goal, SBOM included
Alpine (alpine:3.19) - ~7MB, minimal attack surface
Distroless (gcr.io/distroless/*) - ~2MB, no shell
Slim variants (node:20-slim) - ~70MB, balanced

Key rules:

Always specify exact version tags: node:20.11.0-alpine3.19
Never use latest (unpredictable, breaks reproducibility)
Use official images from trusted registries
Match base image to actual needs

Dockerfile Structure

Optimal layer ordering (least to most frequently changing):

1. Base image and system dependencies
2. Application dependencies (package.json, requirements.txt, etc.)
3. Application code
4. Configuration and metadata

Rationale: Docker caches layers. If code changes but dependencies don't, cached dependency layers are reused, speeding up builds.

Example:

FROM python:3.12-slim
 
# 1. System packages (rarely change)

Multi-Stage Builds

Use multi-stage builds to separate build dependencies from runtime:

Benefits:

Smaller final images (no build tools)
Better security (fewer attack vectors)
Faster deployment (smaller upload/download)

Layer Optimization

Combine commands to reduce layers and image size:

.dockerignore

Always create .dockerignore to exclude unnecessary files:

Container Runtime Best Practices

Security

Resource Management

Always set resource limits in production:

Health Checks

Implement health checks for all long-running containers:

Or in compose:

Logging

Configure proper logging to prevent disk fill-up:

Or system-wide in /etc/docker/daemon.json:

Restart Policies

Docker Compose Best Practices

File Structure

Network Isolation

Environment Variables

Important:

Add .env to .gitignore
Provide .env.example as template
Never commit secrets to version control

Dependency Management

Production Best Practices

Image Tagging Strategy

Secrets Management

Never do this:

Do this:

Monitoring & Observability

Backup Strategy

Update Strategy

Platform-Specific Best Practices

Linux

Use user namespace remapping for added security
Leverage native performance advantages
Use Alpine for smallest images
Configure SELinux/AppArmor profiles
Use systemd for Docker daemon management

macOS

Allocate sufficient resources in Docker Desktop
Use :delegated or :cached for bind mounts
Consider multi-platform builds for ARM (M1/M2)
Limit file sharing to necessary directories

Windows

Choose container type: Windows or Linux
Use forward slashes in paths
Ensure drives are shared in Docker Desktop
Be aware of line ending differences (CRLF vs LF)
Consider WSL2 backend for better performance

Performance Best Practices

Build Performance

Image Size

Use multi-stage builds
Choose minimal base images
Clean up in the same layer
Use .dockerignore
Remove build dependencies

Runtime Performance

Security Best Practices Summary

Image Security:

Use official, minimal base images
Scan for vulnerabilities (Docker Scout, Trivy)
Don't include secrets in layers
Run as non-root user
Keep images updated

Runtime Security:

Drop capabilities
Use read-only filesystem
Set resource limits
Enable security options
Isolate networks
Use secrets management

Compliance:

Follow CIS Docker Benchmark
Implement container scanning in CI/CD
Use signed images (Docker Content Trust)
Maintain audit logs
Regular security reviews

Common Anti-Patterns to Avoid

❌ Don't:

Run as root
Use --privileged
Mount Docker socket
Use latest tag
Hardcode secrets
Skip health checks
Ignore resource limits
Use huge base images
Skip vulnerability scanning
Expose unnecessary ports
Use inefficient layer caching
Commit secrets to Git

✅ Do:

Run as non-root
Use minimal capabilities
Isolate containers
Tag with versions
Use secrets management
Implement health checks
Set resource limits
Use minimal images
Scan regularly
Apply least privilege
Optimize build cache
Use .env.example templates

Checklist for Production-Ready Images

This skill represents current Docker best practices. Always verify against official documentation for the latest recommendations, as Docker evolves continuously.`

npx skills add josiahsiegel/claude-plugin-marketplace --skill docker-best-practices

Documentation

SKILL.md

docker-best-practices | SkillBundle

# Build stage
FROM node:20-alpine AS builder
WORKDIR /app
COPY package*.json ./
RUN npm ci
COPY . .
RUN npm run build
 
# Production stage
FROM node:20-alpine AS runtime
WORKDIR /app
# Only copy what's needed for runtime
COPY --from=builder /app/dist ./dist
COPY --from=builder /app/node_modules ./node_modules
USER node
CMD ["node", "dist/server.js"]

# Bad - 3 layers, cleanup doesn't reduce size
RUN apt-get update
RUN apt-get install -y curl
RUN rm -rf /var/lib/apt/lists/*
 
# Good - 1 layer, cleanup effective
RUN apt-get update && \
    apt-get install -y --no-install-recommends curl && \
    rm -rf /var/lib/apt/lists/*

# Version control
.git
.gitignore
 
# Dependencies
node_modules
__pycache__
*.pyc
 
# IDE
.vscode
.idea
 
# OS
.DS_Store
Thumbs.db
 
# Logs
*.log
logs/
 
# Testing
coverage/
.nyc_output
*.test.js
 
# Documentation
README.md
docs/
 
# Environment
.env
.env.local
*.local

docker run \
  # Run as non-root
  --user 1000:1000 \
  # Drop all capabilities, add only needed ones
  --cap-drop=ALL \
  --cap-add=NET_BIND_SERVICE \
  # Read-only filesystem
  --read-only \
  # Temporary writable filesystems
  --tmpfs /tmp:noexec,nosuid \
  # No new privileges
  --security-opt="no-new-privileges:true" \
  # Resource limits
  --memory="512m" \
  --cpus="1.0" \
  my-image

# docker-compose.yml
services:
  app:
    deploy:
      resources:
        limits:
          cpus: '2.0'
          memory: 1G
        reservations:
          cpus: '1.0'
          memory: 512M

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

services:
  app:
    healthcheck:
      test: ["CMD", "curl", "-f", "http://localhost/health"]
      interval: 30s
      timeout: 3s
      retries: 3
      start_period: 40s

services:
  app:
    logging:
      driver: "json-file"
      options:
        max-size: "10m"
        max-file: "3"

{
  "log-driver": "json-file",
  "log-opts": {
    "max-size": "10m",
    "max-file": "3"
  }
}

services:
  app:
    # For development
    restart: "no"
 
    # For production
    restart: unless-stopped
 
    # Or with fine-grained control (Swarm mode)
    deploy:
      restart_policy:
        condition: on-failure
        delay: 5s
        max_attempts: 3
        window: 120s

# No version field needed (Compose v2.40.3+)
 
services:
  # Service definitions
  web:
    # ...
  api:
    # ...
  database:
    # ...
 
networks:
  # Custom networks (preferred)
  frontend:
  backend:
    internal: true
 
volumes:
  # Named volumes (preferred for persistence)
  db-data:
  app-data:
 
configs:
  # Configuration files (Swarm mode)
  app-config:
    file: ./config/app.conf
 
secrets:
  # Secrets (Swarm mode)
  db-password:
    file: ./secrets/db_pass.txt

networks:
  frontend:
    driver: bridge
  backend:
    driver: bridge
    internal: true  # No external access
 
services:
  web:
    networks:
      - frontend
 
  api:
    networks:
      - frontend
      - backend
 
  database:
    networks:
      - backend  # Not accessible from frontend

services:
  app:
    # Load from file (preferred for non-secrets)
    env_file:
      - .env
 
    # Inline for service-specific vars
    environment:
      - NODE_ENV=production
      - LOG_LEVEL=info
 
    # For Swarm mode secrets
    secrets:
      - db_password

services:
  api:
    depends_on:
      database:
        condition: service_healthy  # Wait for health check
      redis:
        condition: service_started   # Just wait for start

# Use semantic versioning
my-app:1.2.3
my-app:1.2
my-app:1
my-app:latest
 
# Include git commit for traceability
my-app:1.2.3-abc123f
 
# Environment tags
my-app:1.2.3-production
my-app:1.2.3-staging

# BAD - secret in layer history
ENV API_KEY=secret123
RUN echo "password" > /app/config

# Use Docker secrets (Swarm) or external secret management
docker secret create db_password ./password.txt
 
# Or mount secrets at runtime
docker run -v /secure/secrets:/run/secrets:ro my-app
 
# Or use environment files (not in image)
docker run --env-file /secure/.env my-app

services:
  app:
    # Health checks
    healthcheck:
      test: ["CMD", "curl", "-f", "http://localhost/health"]
      interval: 30s
 
    # Labels for monitoring tools
    labels:
      - "prometheus.io/scrape=true"
      - "prometheus.io/port=9090"
      - "com.company.team=backend"
      - "com.company.version=1.2.3"
 
    # Logging
    logging:
      driver: "json-file"
      options:
        max-size: "10m"
        max-file: "3"

# Backup named volume
docker run --rm \
  -v VOLUME_NAME:/data \
  -v $(pwd):/backup \
  alpine tar czf /backup/backup-$(date +%Y%m%d).tar.gz -C /data .
 
# Restore volume
docker run --rm \
  -v VOLUME_NAME:/data \
  -v $(pwd):/backup \
  alpine tar xzf /backup/backup.tar.gz -C /data

services:
  app:
    # For Swarm mode - rolling updates
    deploy:
      replicas: 3
      update_config:
        parallelism: 1        # Update 1 at a time
        delay: 10s            # Wait 10s between updates
        failure_action: rollback
        monitor: 60s
      rollback_config:
        parallelism: 1
        delay: 5s

// /etc/docker/daemon.json
{
  "userns-remap": "default",
  "log-driver": "json-file",
  "log-opts": {
    "max-size": "10m",
    "max-file": "3"
  },
  "storage-driver": "overlay2",
  "live-restore": true
}

# Better volume performance on macOS
volumes:
  - ./src:/app/src:delegated  # Host writes are delayed
  - ./build:/app/build:cached  # Container writes are cached

# Windows-compatible paths
volumes:
  - C:/Users/name/app:/app  # Forward slashes work
  # or
  - C:\Users\name\app:/app  # Backslashes need escaping in YAML

# Use BuildKit (faster, better caching)
export DOCKER_BUILDKIT=1
 
# Use cache mounts
RUN --mount=type=cache,target=/root/.cache/pip \
    pip install -r requirements.txt
 
# Use bind mounts for dependencies
RUN --mount=type=bind,source=package.json,target=package.json \
    --mount=type=bind,source=package-lock.json,target=package-lock.json \
    --mount=type=cache,target=/root/.npm \
    npm ci

# Install and cleanup in one layer
RUN apt-get update && \
    apt-get install -y --no-install-recommends \
    package1 \
    package2 && \
    apt-get clean && \
    rm -rf /var/lib/apt/lists/*

# Use exec form (no shell overhead)
CMD ["node", "server.js"]  # Good
# vs
CMD node server.js         # Bad - spawns shell
 
# Optimize signals
STOPSIGNAL SIGTERM
 
# Run as non-root (slightly faster, much more secure)
USER appuser