Dockerfile Optimizer

Dockerfile Optimizer

Analyzes existing Dockerfiles and delivers concrete before/after improvements for layer caching, image size, build speed, and security.

When to Use / When Not to Use

Process

Two-pass approach: First pass — analyze all 8 checks and note all issues before touching anything. Second pass — apply fixes. This prevents fixing one visible issue while missing others that interact with it.

For a detailed antipatterns checklist per check, read references/antipatterns.md. For a ready-to-use .dockerignore template, read references/dockerignore-template.md.

The Mental Model: Layers Are Cache Keys

Docker builds images as a stack of immutable layers. Each instruction (RUN, COPY, ADD) creates a new layer. The build cache invalidates a layer — and every layer after it — the moment its instruction or its inputs change.

Layer order is your primary optimization lever. Put instructions that change rarely at the top; put instructions that change often (your application code) at the bottom.

# Bad — copies source before installing deps; any code change re-runs npm install
COPY . .
RUN npm ci

# Good — deps cached separately; code changes only rebuild the last two layers
COPY package*.json ./
RUN npm ci
COPY . .

The 8-Check Analysis Framework

Work through these in order during the first pass. Note every finding before making any change.

1. Base Image Selection

Avoid latest in production. Pin to a digest or at minimum a minor version: node:20.11-alpine3.19.

2. Multi-Stage Builds

Multi-stage builds are the single highest-impact optimization available. They let you use a fat builder image with compilers and dev tools, then copy only the final artifact into a minimal runtime image.

# Stage 1: build
FROM node:20-alpine AS builder
WORKDIR /app
COPY package*.json ./
RUN npm ci
COPY . .
RUN npm run build

# Stage 2: runtime — only the built output, no node_modules, no source
FROM node:20-alpine AS runtime
WORKDIR /app
COPY --from=builder /app/dist ./dist
COPY --from=builder /app/node_modules ./node_modules

3. Layer Count and RUN Consolidation

# Bad — three layers, apt cache left in layer 1
RUN apt-get update
RUN apt-get install -y curl
RUN rm -rf /var/lib/apt/lists/*

# Good — one layer, cache never committed
RUN apt-get update \
    && apt-get install -y --no-install-recommends curl \
    && rm -rf /var/lib/apt/lists/*

4. .dockerignore

Without a .dockerignore, COPY . . sends the entire build context to the Docker daemon — including node_modules, .git, test fixtures, and local config files. See references/dockerignore-template.md for a ready-to-use template.

5. Non-Root User

RUN addgroup --system --gid 1001 appgroup \
    && adduser --system --uid 1001 --ingroup appgroup appuser
USER appuser

Many official images ship a pre-created non-privileged user (node, www-data) — use it: USER node.

6. COPY vs ADD

Use COPY unless you specifically need ADD's features (auto-extracting tarballs). ADD with URLs bypasses the build cache unpredictably.

7. CMD vs ENTRYPOINT

Use exec form (["executable", "arg"]), not shell form (executable arg). Shell form spawns a shell as PID 1, which does not forward signals correctly.

# Shell form — PID 1 is /bin/sh, signals not forwarded
CMD node server.js

# Exec form — PID 1 is node, SIGTERM reaches your process
ENTRYPOINT ["node"]
CMD ["server.js"]

8. Secret Handling

Never put secrets in ENV or ARG — they are visible in docker history. Use BuildKit secrets for build-time, and runtime injection for runtime.

# Good — secret mounted at build time, never committed to a layer
RUN --mount=type=secret,id=api_key \
    API_KEY=$(cat /run/secrets/api_key) ./fetch-assets.sh

Output Template

For each Dockerfile reviewed, provide:

1. Before/after diff with inline comments explaining each change
2. Size impact estimate (if measurable from layer analysis)
3. Cache hit improvement explanation
4. Security issues found with severity (Critical/High/Medium)

What Claude Does / What You Do

Measuring Impact

After optimizing, measure:

• docker image ls <image> — compare sizes before and after
• docker build --no-cache . — cold build time
• docker build . (after changing only source) — warm build time
• docker history <image> — layer breakdown; look for unexpectedly large layers
• dive <image> (third-party tool) — interactive layer explorer showing wasted space

Related Skills

• develop:sre-engineer — production container deployment and health checks
• develop:chaos-engineer — resilience testing for containerized services
• develop:cli-developer — wrapping container tooling in a CLI