Docker Development Skill

A Claude Code skill for containerizing applications with Docker — covering Dockerfile optimization, multi-stage builds, Docker Compose workflows, networking, volume management, and production deployment patterns.

When to Use This Skill

Choose this skill when:

• Containerizing an application for the first time
• Optimizing Docker images for smaller size and faster builds
• Setting up multi-service development environments with Docker Compose
• Debugging container networking, volume, or permission issues
• Creating production-ready Docker configurations
• Migrating from local development to containerized workflows

Consider alternatives when:

• You need container orchestration at scale (use a Kubernetes skill)
• You need CI/CD pipeline configuration (use a CI/CD skill)
• You need cloud infrastructure provisioning (use an IaC skill)

Quick Start

Copy
# Add to your Claude Code project
claude mcp add docker-module

# Create an optimized Dockerfile
claude "create a production Dockerfile for my Node.js application"

# Set up Docker Compose for local development
claude "set up Docker Compose with app, database, and Redis"

Copy
# Optimized multi-stage Dockerfile for Node.js
FROM node:20-alpine AS base
WORKDIR /app

FROM base AS deps
COPY package.json package-lock.json ./
RUN npm ci --only=production

FROM base AS build
COPY package.json package-lock.json ./
RUN npm ci
COPY . .
RUN npm run build

FROM base AS production
ENV NODE_ENV=production
RUN addgroup -g 1001 -S nodejs && adduser -S nextjs -u 1001
COPY --from=deps /app/node_modules ./node_modules
COPY --from=build /app/dist ./dist
COPY --from=build /app/package.json ./
USER nextjs
EXPOSE 3000
CMD ["node", "dist/index.js"]

Core Concepts

Image Optimization

Technique	Savings	How
Alpine base image	900MB → 100MB	FROM node:20-alpine instead of node:20
Multi-stage build	Remove build deps	Separate build and runtime stages
Layer caching	Faster rebuilds	COPY package.json before source code
.dockerignore	Smaller context	Exclude node_modules, .git, docs
Non-root user	Security	RUN adduser + USER appuser

Docker Compose Development

Copy
# docker-compose.yml
services:
  app:
    build:
      context: .
      target: build  # Use build stage for dev
    ports:
      - "3000:3000"
    volumes:
      - .:/app
      - /app/node_modules  # Prevent overwrite
    environment:
      - DATABASE_URL=postgresql://user:pass@db:5432/mydb
      - REDIS_URL=redis://redis:6379
    depends_on:
      db: { condition: service_healthy }
      redis: { condition: service_started }

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

  redis:
    image: redis:7-alpine
    ports:
      - "6379:6379"

volumes:
  pgdata:

Configuration

Parameter	Type	Default	Description
base_image	string	"node:20-alpine"	Base Docker image
multi_stage	boolean	true	Use multi-stage builds
non_root_user	boolean	true	Create and use non-root user
healthcheck	boolean	true	Add healthcheck instructions
compose_version	string	"3.8"	Docker Compose file version
volumes_for_data	boolean	true	Use named volumes for persistent data
build_cache	boolean	true	Optimize layer caching order

Best Practices

1. Copy dependency files before source code — COPY package*.json ./ then RUN npm ci then COPY . .; this lets Docker cache the dependency layer and only rebuild when dependencies change, not when code changes.

2. Use multi-stage builds for production images — build stage installs dev dependencies and compiles; production stage copies only the compiled output and production dependencies, resulting in images that are 60-80% smaller.

3. Never run containers as root in production — create a non-root user with adduser and switch with USER; if the container is compromised, the attacker has limited permissions.

4. Add healthchecks to all service containers — Docker Compose depends_on with condition: service_healthy prevents your app from starting before the database is actually ready, not just running.

5. Use .dockerignore to exclude unnecessary files — exclude node_modules, .git, *.md, tests/, and other non-runtime files to reduce build context size and speed up builds.

Common Issues

node_modules on host overwrites container's node_modules — When mounting source code as a volume, the host's empty node_modules replaces the container's installed modules. Add an anonymous volume: /app/node_modules in your volumes to preserve it.

Container can't connect to host's database — Use host.docker.internal instead of localhost to connect from a container to a service running on the host machine. In Docker Compose, use the service name (e.g., db) as the hostname.

Image rebuilds are slow despite no dependency changes — Your COPY order is wrong. If COPY . . comes before RUN npm ci, every source code change invalidates the dependency cache. Always copy and install dependencies first.