/writing-dockerfiles

name: writing-dockerfiles
description: Writing optimized, secure, multi-stage Dockerfiles with language-specific patterns (Python, Node.js, Go, Rust), BuildKit features, and distroless images. Use when containerizing applications, optimizing existing Dockerfiles, or reducing image sizes.

Writing Dockerfiles

Create production-grade Dockerfiles with multi-stage builds, security hardening, and language-specific optimizations.

When to Use This Skill

Invoke when:

• "Write a Dockerfile for [Python/Node.js/Go/Rust] application"
• "Optimize this Dockerfile to reduce image size"
• "Use multi-stage build for..."
• "Secure Dockerfile with non-root user"
• "Use distroless base image"
• "Add BuildKit cache mounts"
• "Prevent secrets from leaking in Docker layers"

Quick Decision Framework

Ask three questions to determine the approach:

**1. What language?**

• Python → See `references/python-dockerfiles.md`
• Node.js → See `references/nodejs-dockerfiles.md`
• Go → See `references/go-dockerfiles.md`
• Rust → See `references/rust-dockerfiles.md`
• Java → See `references/java-dockerfiles.md`

**2. Is security critical?**

• YES → Use distroless runtime images (see `references/security-hardening.md`)
• NO → Use slim/alpine base images

**3. Is image size critical?**

• YES (<50MB) → Multi-stage + distroless + static linking
• NO (<500MB) → Multi-stage + slim base images

Core Concepts

Multi-Stage Builds

Separate build environment from runtime environment to minimize final image size.

**Pattern:**

# Stage 1: Build
FROM build-image AS builder
RUN compile application

# Stage 2: Runtime
FROM minimal-runtime-image
COPY --from=builder /app/binary /app/
CMD ["/app/binary"]

**Benefits:**

• 80-95% smaller images (excludes build tools)
• Improved security (no compilers in production)
• Faster deployments
• Better layer caching

Base Image Selection

**Decision matrix:**

| Language | Build Stage | Runtime Stage | Final Size | |----------|-------------|---------------|------------| | Go (static) | `golang:1.22-alpine` | `gcr.io/distroless/static-debian12` | 10-30MB | | Rust (static) | `rust:1.75-alpine` | `scratch` | 5-15MB | | Python | `python:3.12-slim` | `python:3.12-slim` | 200-400MB | | Node.js | `node:20-alpine` | `node:20-alpine` | 150-300MB | | Java | `maven:3.9-eclipse-temurin-21` | `eclipse-temurin:21-jre-alpine` | 200-350MB |

**Distroless images** (Google-maintained):

• `gcr.io/distroless/static-debian12` → Static binaries (2MB)
• `gcr.io/distroless/base-debian12` → Dynamic binaries with libc (20MB)
• `gcr.io/distroless/python3-debian12` → Python runtime (60MB)
• `gcr.io/distroless/nodejs20-debian12` → Node.js runtime (150MB)

See `references/base-image-selection.md` for complete comparison.

BuildKit Features

Enable BuildKit for advanced caching and security:

export DOCKER_BUILDKIT=1
docker build .
# OR
docker buildx build .

**Key features:**

• `--mount=type=cache` → Persistent package manager caches
• `--mount=type=secret` → Inject secrets without storing in layers
• `--mount=type=ssh` → SSH agent forwarding for private repos
• Parallel stage execution
• Improved layer caching

See `references/buildkit-features.md` for detailed patterns.

Layer Optimization

Order Dockerfile instructions from least to most frequently changing:

# 1. Base image (rarely changes)
FROM python:3.12-slim

# 2. System packages (rarely changes)
RUN apt-get update && apt-get install -y build-essential

# 3. Dependencies manifest (changes occasionally)
COPY requirements.txt .
RUN pip install -r requirements.txt

# 4. Application code (changes frequently)
COPY . .

# 5. Runtime configuration (rarely changes)
CMD ["python", "app.py"]

**BuildKit cache mounts:**

RUN --mount=type=cache,target=/root/.cache/pip \
    pip install -r requirements.txt

Cache persists across builds, eliminating redundant downloads.

Security Hardening

**Essential security practices:**

**1. Non-root users**

# Debian/Ubuntu
RUN useradd -m -u 1000 appuser && chown -R appuser:appuser /app
USER appuser

# Alpine
RUN adduser -D -u 1000 appuser && chown -R appuser:appuser /app
USER appuser

# Distroless (built-in)
USER nonroot:nonroot

**2. Secret management**

# ❌ NEVER: Secret in layer history
RUN git clone https://${GITHUB_TOKEN}@github.com/private/repo.git

# ✅ ALWAYS: BuildKit secret mount
RUN --mount=type=secret,id=github_token \
    TOKEN=$(cat /run/secrets/github_token) && \
    git clone https://${TOKEN}@github.com/private/repo.git

Build with:

docker buildx build --secret id=github_token,src=./token.txt .

**3. Vulnerability scanning**

# Trivy (recommended)
trivy image myimage:latest

# Docker Scout
docker scout cves myimage:latest

**4. Health checks**

HEALTHCHECK --interval=30s --timeout=3s --start-period=10s --retries=3 \
  CMD wget --no-verbose --tries=1 --spider http://localhost:8080/health || exit 1

See `references/security-hardening.md` for comprehensive hardening patterns.

.dockerignore Configuration

Create `.dockerignore` to exclude unnecessary files:

# Version control
.git
.gitignore

# CI/CD
.github
.gitlab-ci.yml

# IDE
.vscode
.idea

# Testing
tests/
coverage/
**/*_test.go
**/*.test.js

# Build artifacts
node_modules/
dist/
build/
target/
__pycache__/

# Environment
.env
.env.local
*.log

Reduces build context size and prevents leaking secrets.

Language-Specific Patterns

Python Quick Reference

**Three approaches:**

1. **pip (simple)** → Single-stage, requirements.txt 2. **poetry (production)** → Multi-stage, virtual environment 3. **uv (fastest)** → 10-100x faster than pip

**Example: Poetry multi-stage**

FROM python:3.12-slim AS builder
RUN --mount=type=cache,target=/root/.cache/pip \
    pip install poetry==1.7.1

COPY pyproject.toml poetry.lock ./
RUN poetry export -f requirements.txt --output requirement