Docker Skill
When to activate
- Writing or optimizing Dockerfiles for production
- Setting up multi-stage builds to reduce image size
- Writing Docker Compose files for local development
- Debugging container startup failures or layer cache issues
- Configuring non-root users, health checks, and image security
- Setting up .dockerignore for efficient builds
- Writing build scripts or CI/CD Docker build pipelines
When NOT to use
- Kubernetes manifests (use the Kubernetes skill)
- Buildpacks (Heroku, Cloud Native Buildpacks) — different build system
- Virtual machine provisioning (different abstraction level)
- Nix-based reproducible builds
Instructions
Production Dockerfile structure
Always use multi-stage builds for compiled languages and Node.js:
# Stage 1: Build
FROM node:20-alpine AS builder
WORKDIR /app
COPY package*.json ./
RUN npm ci --only=production
# Stage 2: Runtime — minimal image
FROM node:20-alpine AS runtime
RUN addgroup -S appgroup && adduser -S appuser -G appgroup
WORKDIR /app
COPY --from=builder /app/node_modules ./node_modules
COPY . .
USER appuser
EXPOSE 8080
HEALTHCHECK --interval=30s --timeout=5s --start-period=10s --retries=3 \
CMD wget -qO- http://localhost:8080/healthz || exit 1
CMD ["node", "server.js"]
Security rules
- Never run as root in production — always create and switch to a non-root user
- Never use
latest tag — pin to a specific version or digest
- Prefer Alpine or distroless base images over full Debian/Ubuntu
- Never copy
.env files into the image — pass secrets as runtime env vars
- Scan images with
docker scout or Trivy before pushing to production
Layer caching optimization
Order Dockerfile instructions from least-to-most frequently changing:
- Base image (changes rarely)
- System dependencies (
apt-get, apk add)
- Package manager files (
package.json, requirements.txt)
- Package install (
npm ci, pip install)
- Application code (
COPY . .) — changes most often, must be last
.dockerignore — always include
node_modules/
.git/
.env
.env.*
*.md
Dockerfile*
docker-compose*
.dockerignore
coverage/
.nyc_output/
__pycache__/
*.pyc
.pytest_cache/
Docker Compose for local development
services:
app:
build:
context: .
target: builder # Use build stage, not runtime stage locally
volumes:
- .:/app # Hot reload
- /app/node_modules # Don't overwrite container node_modules
ports:
- "8080:8080"
environment:
- NODE_ENV=development
depends_on:
db:
condition: service_healthy
db:
image: postgres:16-alpine
environment:
POSTGRES_USER: app
POSTGRES_PASSWORD: dev_password # Dev only — never production
POSTGRES_DB: appdb
ports:
- "5432:5432"
healthcheck:
test: ["CMD-SHELL", "pg_isready -U app -d appdb"]
interval: 5s
timeout: 5s
retries: 5
volumes:
- postgres_data:/var/lib/postgresql/data
volumes:
postgres_data:
Common build failures
COPY fails silently if source doesn't exist — check .dockerignore isn't excluding needed files
- Layer cache invalidated unexpectedly — check if a
COPY before install steps is pulling in changed files
- Permission denied at runtime — check file ownership when using
COPY --from with a non-root user
Example
User: Write a production Dockerfile for a Python FastAPI app with multi-stage build, non-root user, and health check.
Expected output:
- Stage 1 (builder):
python:3.12-slim, install dependencies with pip install --no-cache-dir
- Stage 2 (runtime):
python:3.12-slim, non-root user, copy only wheels/deps from builder + app code
HEALTHCHECK hitting /healthz endpoint
CMD ["uvicorn", "main:app", "--host", "0.0.0.0", "--port", "8080"]
.dockerignore covering __pycache__, .env, .git, *.pyc
1---2name: "docker"3description: "Dockerfile best practices, multi-stage builds, Compose services, networking, volumes, build caching"4metadata:5 source: https://skillmd.com/skills/uitbreidenos/docker6---78# Docker Skill910## When to activate11- Writing or optimizing Dockerfiles for production12- Setting up multi-stage builds to reduce image size13- Writing Docker Compose files for local development14- Debugging container startup failures or layer cache issues15- Configuring non-root users, health checks, and image security16- Setting up .dockerignore for efficient builds17- Writing build scripts or CI/CD Docker build pipelines1819## When NOT to use20- Kubernetes manifests (use the Kubernetes skill)21- Buildpacks (Heroku, Cloud Native Buildpacks) — different build system22- Virtual machine provisioning (different abstraction level)23- Nix-based reproducible builds2425## Instructions2627### Production Dockerfile structure28Always use multi-stage builds for compiled languages and Node.js:2930```dockerfile31# Stage 1: Build32FROM node:20-alpine AS builder33WORKDIR /app34COPY package*.json ./35RUN npm ci --only=production3637# Stage 2: Runtime — minimal image38FROM node:20-alpine AS runtime39RUN addgroup -S appgroup && adduser -S appuser -G appgroup40WORKDIR /app41COPY --from=builder /app/node_modules ./node_modules42COPY . .43USER appuser44EXPOSE 808045HEALTHCHECK --interval=30s --timeout=5s --start-period=10s --retries=3 \46 CMD wget -qO- http://localhost:8080/healthz || exit 147CMD ["node", "server.js"]48```4950### Security rules51- Never run as root in production — always create and switch to a non-root user52- Never use `latest` tag — pin to a specific version or digest53- Prefer Alpine or distroless base images over full Debian/Ubuntu54- Never copy `.env` files into the image — pass secrets as runtime env vars55- Scan images with `docker scout` or Trivy before pushing to production5657### Layer caching optimization58Order Dockerfile instructions from least-to-most frequently changing:591. Base image (changes rarely)602. System dependencies (`apt-get`, `apk add`)613. Package manager files (`package.json`, `requirements.txt`)624. Package install (`npm ci`, `pip install`)635. Application code (`COPY . .`) — changes most often, must be last6465### .dockerignore — always include66```67node_modules/68.git/69.env70.env.*71*.md72Dockerfile*73docker-compose*74.dockerignore75coverage/76.nyc_output/77__pycache__/78*.pyc79.pytest_cache/80```8182### Docker Compose for local development83```yaml84services:85 app:86 build:87 context: .88 target: builder # Use build stage, not runtime stage locally89 volumes:90 - .:/app # Hot reload91 - /app/node_modules # Don't overwrite container node_modules92 ports:93 - "8080:8080"94 environment:95 - NODE_ENV=development96 depends_on:97 db:98 condition: service_healthy99100 db:101 image: postgres:16-alpine102 environment:103 POSTGRES_USER: app104 POSTGRES_PASSWORD: dev_password # Dev only — never production105 POSTGRES_DB: appdb106 ports:107 - "5432:5432"108 healthcheck:109 test: ["CMD-SHELL", "pg_isready -U app -d appdb"]110 interval: 5s111 timeout: 5s112 retries: 5113 volumes:114 - postgres_data:/var/lib/postgresql/data115116volumes:117 postgres_data:118```119120### Common build failures121- `COPY` fails silently if source doesn't exist — check `.dockerignore` isn't excluding needed files122- Layer cache invalidated unexpectedly — check if a `COPY` before install steps is pulling in changed files123- Permission denied at runtime — check file ownership when using `COPY --from` with a non-root user124125## Example126127**User:** Write a production Dockerfile for a Python FastAPI app with multi-stage build, non-root user, and health check.128129**Expected output:**130- Stage 1 (builder): `python:3.12-slim`, install dependencies with `pip install --no-cache-dir`131- Stage 2 (runtime): `python:3.12-slim`, non-root user, copy only wheels/deps from builder + app code132- `HEALTHCHECK` hitting `/healthz` endpoint133- `CMD ["uvicorn", "main:app", "--host", "0.0.0.0", "--port", "8080"]`134- `.dockerignore` covering `__pycache__`, `.env`, `.git`, `*.pyc`135136---