Dockerfile Authoring Skill

What This Skill Does

Creates enterprise-grade, production-ready Dockerfiles following the Universal Dockerfile Platinum+ Standard with:

• •Multi-stage builds (deps → builder → runner)
• •BuildKit 1.20+ features (cache mounts, secret mounts, heredocs)
• •Security hardening (non-root, distroless, read-only FS)
• •Cloud-native compatibility (K8s probes, 12-factor)

What This Skill Does NOT Do

• •Write docker-compose.yml files (use containerization skill)
• •Create Kubernetes manifests or Helm charts
• •Optimize images for size only (security takes priority)

Before Implementation

Gather context to ensure successful implementation:

Only ask user for THEIR specific requirements (domain expertise is in this skill).

Quick Pattern Selection

Language?
├─ Node.js → Framework?
│  ├─ Next.js → references/language-patterns.md#nextjs-platinum-pattern
│  ├─ Express → references/language-patterns.md#expressjs-platinum-pattern
│  └─ Bun runtime → references/language-patterns.md#nextjs-with-bun
├─ Python → Package Manager?
│  ├─ uv → references/language-patterns.md#fastapi-with-uv
│  ├─ poetry → references/language-patterns.md#fastapi-with-poetry
│  ├─ pdm → references/language-patterns.md#fastapi-with-pdm
│  └─ Django → references/language-patterns.md#django-platinum-pattern
├─ Go → CGO?
│  ├─ No → references/language-patterns.md#standard-go-service (distroless)
│  └─ Yes → references/language-patterns.md#go-with-cgo-dependencies
├─ Java → Framework?
│  ├─ Spring Boot → references/language-patterns.md#spring-boot-platinum-pattern
│  └─ Micronaut → references/language-patterns.md#micronaut-platinum-pattern
└─ Rust → Database?
   ├─ PostgreSQL → references/language-patterns.md#rust-with-dieselpostgresql
   └─ None → references/language-patterns.md#standard-rust-service

Grep Patterns for References

# Language patterns
grep -n "### Node.js\|### Python\|### Go\|### Java\|### Rust" references/language-patterns.md

# Security patterns
grep -n "Non-Root\|Secret\|Healthcheck\|Anti-Patterns" references/security-patterns.md

# BuildKit cache mounts
grep -n "mount=type=cache\|--security\|--parents\|heredoc" references/buildkit-features.md

# CI/CD patterns
grep -n "GitHub Actions\|Kubernetes\|dockerignore" references/cicd-patterns.md

Overview

Creates Dockerfiles ensuring maximum security, determinism, and cloud-native compatibility through strict multi-stage builds, advanced BuildKit features, and modern security practices.

Required Information (Must Have)

1. •Language & Runtime - Node / Python / Go / Java / Rust / Bun / Deno
2. •Build Tool - npm / pnpm / yarn / bun / uv / poetry / pdm / pip / gradle / cargo
3. •Entrypoint - Command to start the app (or infer from codebase)

Optional Information (Defaults Provided)

Handling Missing Information

When user doesn't provide specific information:

Principle: Make reasonable defaults but add comments indicating where user should customize.

# TODO: Update port if your app uses different default
EXPOSE 3000

# TODO: Replace with your actual start command
CMD ["node", "server.js"]

🏗️ Phase 2: Apply Platinum Standards

2.1 Base Image Rules

• •ONLY use: Docker Official Images or well-known vendor images (node, python, eclipse-temurin)
• •Prefer: slim variants, Debian (bookworm/bullseye)
• •NEVER use: latest tags, random GitHub images
• •Always pin: Runtime MAJOR version, optionally MINOR for Platinum

2.2 Multi-Stage Build (MANDATORY)

Every production Dockerfile MUST include:

• •deps – dependency installation
• •builder – compilation / build
• •runner – minimal runtime No exceptions.

2.3 Dependency Installation Rules

• •Copy ONLY dependency manifests first
• •Lockfiles are mandatory
• •Fail if lockfile mismatch

Examples:

COPY package.json pnpm-lock.yaml ./
RUN pnpm install --frozen-lockfile

COPY pyproject.toml uv.lock ./
RUN uv sync --frozen

2.4 Build-time Environment Variables

Golden Rule: If a variable is needed ONLY for build, it MUST NOT exist in runtime image.

Pattern:

ARG DATABASE_URL=dummy
ENV DATABASE_URL=$DATABASE_URL
RUN build-command
ENV DATABASE_URL=""  # Clear after build

• •NEXT_PUBLIC_* → build-time allowed
• •Secrets → NEVER copied to runtime

2.5 Runtime Image Rules

Runtime image MUST contain only:

• •Built artifacts
• •Runtime binaries

NEVER contain:

• •Package managers
• •Source files (unless required)
• •.env files
• •Build caches

2.6 Non-Root Execution (MANDATORY)

RUN addgroup --system app && \
    adduser --system --ingroup app --shell /sbin/nologin app
USER app

2.7 Healthcheck Rules

• •MUST exist
• •Prefer native runtime (Node/Python)
• •Avoid curl unless unavoidable

Examples:

HEALTHCHECK CMD node -e "fetch('http://localhost:3000/health')..."

2.8 Entrypoint Rules

• •Use exec form
• •One process per container
• •Correct signal handling

CMD ["node", "server.js"]

🏗️ Phase 3: Security & Performance

3.1 Security Hardening Rules (Platinum)

• •No secrets in image layers
• •Minimal OS packages
• •Read-only root FS compatible
• •PodSecurity restricted compatible
• •No privileged ports (<1024)

3.2 Performance & Caching Rules

• •Cache dependency installs
• •Use BuildKit cache mounts when available
• •Minimize layer count
• •Avoid invalidating cache unnecessarily

🏗️ Phase 4: Validation & Output

4.1 Validation Checklist (Agent MUST self-check)

Before outputting Dockerfile, validate:

• • No latest tags
• • Lockfile used
• • Non-root user
• • Multi-stage build
• • Secrets not leaked
• • Healthcheck exists
• • Entrypoint is exec-form
• • Runtime image minimal
• • BuildKit cache mounts used
• • .dockerignore recommended if needed

4.2 Output Requirements

• •Output only the Dockerfile
• •Include comments explaining each stage
• •Follow Platinum+ standards unless told otherwise
• •Never invent dependencies
• •Never guess secrets
• •Recommend .dockerignore patterns when applicable

4.3 Common Build Failures & Recovery

When builds fail, diagnose and suggest fixes:

Pattern for documenting troubleshooting in Dockerfile:

# Troubleshooting:
# - If build fails: docker build --no-cache .
# - If port conflicts: docker run -p HOSTPORT:3000 ...
# - For private packages: docker build --secret id=npm_token .

🚀 Phase 5: Platinum+ Advanced Features

5.1 Advanced BuildKit Features

Secret Mounts (for private registries, SSH keys)

Use secret mounts instead of ARG for sensitive build-time data:

# Mount secrets without leaking them into layers
RUN --mount=type=secret,id=npm_token \
    npm config set //registry.npmjs.org/:_authToken=$(cat /run/secrets/npm_token) && \
    npm install

Build with: docker build --secret id=npm_token,src=.npmrc .

Bind Mounts (for efficient builds)

Mount build context without copying:

# Build without copying source to image
FROM golang:1.22-slim AS builder
WORKDIR /app
COPY go.mod go.sum ./
RUN go mod download
RUN --mount=type=bind,target=. \
    go build -o /app/server .

SSH Mounts (for private repos)

Access private Git repositories during build:

RUN --mount=type=ssh \
    go mod download

Build with: docker build --ssh default .

5.2 Multi-Platform Builds

Support multiple architectures (amd64, arm64):

ARG TARGETOS=linux
ARG TARGETARCH=amd64

FROM --platform=$TARGETOS/$TARGETARCH node:22-slim AS deps
# ... rest of build

# For Go, use build args
RUN CGO_ENABLED=0 GOOS=${TARGETOS} GOARCH=${TARGETARCH} \
    go build -o /app/server .

Build with: docker buildx build --platform linux/amd64,linux/arm64 .

5.3 Distroless & Minimal Images

For maximum security, use distroless runtime images:

# Go application with distroless
FROM gcr.io/distroless/static-debian12 AS runner
WORKDIR /
COPY --from=builder /app/server /server
USER 65532:65532
EXPOSE 8080
CMD ["/server"]

Distroless variants:

• •static-debian12 - Static binaries (Go, Rust)
• •base-debian12 - Minimal libc (Python, Node if needed)
• •cc-debian12 - With libgcc (some C++ apps)

Alternatives:

• •Chainguard Images: cgr.dev/chainguard/node:latest
• •Wolfi-based: cgr.dev/chainguard/wolfi-base

5.4 Production Hardening

Init Process for Signal Handling

Add init process for proper signal forwarding:

# Using tini
RUN apt-get update && apt-get install -y tini && rm -rf /var/lib/apt/lists/*
ENTRYPOINT ["/usr/bin/tini", "--"]
CMD ["node", "server.js"]

Or use Docker's built-in init:

docker run --init my-app

Read-Only Root Filesystem

Make runtime filesystem read-only:

# Create writable directories
RUN mkdir -p /tmp /app/logs && \
    chown app:app /tmp /app/logs
USER app
# Use: docker run --read-only --tmpfs /tmp my-app

5.5 .dockerignore

Always create .dockerignore to reduce build context. See references/cicd-patterns.md for complete patterns.

Reference Files

📚 Reference Documentation

Detailed patterns are organized by domain in references/:

📖 External Documentation

For patterns not covered in this skill, consult official resources:

Note: Patterns in this skill reflect current best practices as of 2025. Always verify against latest official documentation.

⚠️ Critical Anti-Patterns (NEVER Do These)

❌ ALWAYS AVOID:

# NEVER use latest tags
FROM node:latest

# NEVER run as root
USER root

# NEVER bake secrets
ENV DATABASE_URL=postgresql://user:pass@prod.db:5432/db

# NEVER include package managers in runtime
RUN npm install && npm run build

# NEVER use curl for health checks
HEALTHCHECK CMD curl http://localhost:3000/health

# NEVER use shell form for CMD
CMD node server.js

✅ ALWAYS DO:

# ALWAYS pin versions
FROM node:22-slim

# ALWAYS use non-root users
RUN addgroup --system app && adduser --system --ingroup app app
USER app

# ALWAYS inject secrets at runtime
# DATABASE_URL set via docker-compose/K8s

# ALWAYS use multi-stage builds
# deps -> builder -> runner

# ALWAYS use native health checks
HEALTHCHECK CMD node -e "fetch('http://127.0.0.1:3000/health')"

# ALWAYS use exec form
CMD ["node", "server.js"]