Dockerfile Antipatterns: How We Cut Image Size by 80% and Build Time by 60%

# Dockerfile Antipatterns: How We Cut Image Size by 80% and Build Time by 60%

Every Dockerfile starts innocent enough. A base image. A COPY . .. A RUN npm install. Maybe someone adds a --no-cache flag if they're feeling virtuous.

Then someone deploys to production, the image scanner flags 47 CVEs in the base OS packages, the security team blocks the deploy, and you spend a day figuring out why your image is 1.2 GB for a 50 KB web service.

I've audited over 200 production Dockerfiles across four companies. The patterns are remarkably consistent. The same mistakes appear again and again — not because engineers are careless, but because Dockerfiles evolve like sedimentary rock. Layers accrete. Nobody deletes anything. The build works, so nobody questions the 12-minute CI pipeline.

This post is the audit I wish I'd received on day one. Here are the exact antipatterns we found, the numbers behind them, and the Dockerfiles we actually run in production.

The Numbers That Matter

Before we talk patterns, let's establish a baseline. Here's what we measured across a sample of 50 production services after our audit:

These aren't heroic numbers. They're the result of applying the same eight patterns to every Dockerfile. No special tooling. No Bazel migration. Just better Dockerfiles.

Antipattern #1: The Kitchen Sink Base Image

# ❌ Antipattern — what most teams start with
FROM node:20-slim

# Or worse:
FROM node:20
# This ships with: npm, yarn, pnpm, git, curl, wget, python3, gcc...
# Actual runtime dependencies: libc, libssl, libz

The node:20 image is 345 MB. The node:20-slim is 144 MB. The node:20-alpine is 72 MB.

If you look at what's actually in these images, the difference isn't Node.js — it's build tools. node:20 ships with a full build toolchain (gcc, make, python3) because the official image is designed for compiling native modules. Most JavaScript projects don't compile native modules. They use prebuilt binaries or avoid native dependencies entirely.

What we actually run in production:

# ✅ Production base for Node.js services
FROM node:20-alpine AS base
# 72 MB instead of 345 MB

# ✅ For Go services
FROM golang:1.22-alpine AS build
# 250 MB with build toolchain — but this is a BUILD stage, not runtime

FROM scratch
# 0 MB — literally nothing
COPY --from=build /app/server /server
EXPOSE 8080
ENTRYPOINT ["/server"]

# ✅ For Rust services
FROM rust:1.80-slim-bookworm AS build
# 500 MB with Rust toolchain — again, build only

FROM gcr.io/distroless/cc-debian12
# 25 MB — just libc and runtime essentials
COPY --from=build /app/target/release/service /service
ENTRYPOINT ["/service"]

The principle: The base image for your build stage can be large. The base image for your runtime stage should be as small as possible.

For Go and Rust binaries that are statically linked, FROM scratch is genuinely zero bytes — no shell, no libc, nothing but your binary. For dynamically linked binaries (most Node.js, Python, Java), use distroless images from Google. They contain only the runtime essentials: your language runtime, libc, timezone data, and CA certificates. No shell. No package manager. No compilers.

# Distroless for Node.js
FROM node:20-alpine AS build
# Install dependencies, build assets, etc.

FROM gcr.io/distroless/nodejs20-debian12
COPY --from=build /app /app
WORKDIR /app
CMD ["dist/index.js"]
# ~85 MB total — and zero CVEs from OS packages

But what if I need debugging access in production? You don't. Use kubectl exec with an ephemeral debug container — it brings its own image and doesn't bloat yours. If your production containers need a shell, your observability is broken. Fix that instead.

Antipattern #2: COPY Everything, Sort Later

# ❌ Antipattern — the naive copy
FROM node:20-alpine
WORKDIR /app
COPY . .
RUN npm install --production
RUN npm run build
EXPOSE 3000
CMD ["node", "dist/index.js"]

This Dockerfile has three problems, and they compound into a fourth:

1. COPY . . copies everything — node_modules, .git, .env, README.md, design assets, test fixtures. This blows up the build context sent to the Docker daemon and invalidates the layer cache on every change.

1. npm install runs after COPY . ., which means every source code change triggers a full dependency install. Even a README edit rebuilds every npm package.

1. No .dockerignore means the Docker daemon loads thousands of unnecessary files.

1. Combined: npm install runs for every commit. A 30-second install becomes a 30-second CI penalty on every push.

# .dockerignore — ship only what's needed
node_modules
.git
.gitignore
*.md
test/
tests/
__tests__/
coverage/
.env
.env.*
docker-compose*.yml
.editorconfig
.eslintrc*
.prettierrc*
tsconfig*.json

The fixed version:

# ✅ Optimised for layer caching
FROM node:20-alpine AS deps
WORKDIR /app

# 1. Copy dependency manifests first — these change rarely
COPY package.json package-lock.json ./
# Or for yarn: COPY package.json yarn.lock ./

# 2. Install dependencies (only when package.json changes)
RUN npm ci --only=production
# npm ci is faster than npm install and respects lockfile

# 3. Copy source code (changes every commit)
FROM deps AS build
WORKDIR /app
COPY --from=deps /app/node_modules ./node_modules
COPY . .
RUN npm run build

# 4. Production runtime — only what's needed
FROM gcr.io/distroless/nodejs20-debian12
WORKDIR /app
COPY --from=build /app/dist ./dist
COPY --from=deps /app/node_modules ./node_modules
CMD ["dist/index.js"]

The caching insight: Docker caches layers by the exact content of the COPY source. package.json changes maybe once a week. Source code changes every commit. By separating them into different layers, npm ci runs only when package.json changes — not on every code edit.

In CI, this means a typical PR commit builds in ~45 seconds (restoring dist and node_modules from cache) instead of ~4 minutes.

Antipattern #3: Ignoring BuildKit

Docker BuildKit has been stable since Docker 23.0 (shipped in February 2023). Most teams still don't use it, or if they do, they don't use the features that matter.

Enable it:

# Either set this environment variable:
export DOCKER_BUILDKIT=1

# Or use the modern syntax (preferred):
docker buildx build --push -t myapp:latest .

# Or set it globally in ~/.docker/config.json:
# { "features": { "buildkit": true } }

BuildKit alone gives you 30-50% faster builds through better parallelisation. But the real wins come from specific features:

--cache-from and --cache-to (Remote Cache)

Without remote caching, CI builds are always cold builds. With BuildKit's remote cache, you can share layers between CI runs:

# In CI: cache to a registry
docker buildx build   --cache-from type=registry,ref=myapp:cache   --cache-to type=registry,ref=myapp:cache,mode=max   --push   -t myapp:latest .

# The mode=max flag caches all layers, not just those exported.
# This uses significantly more storage in your registry
# but gives you full cache hits on every CI run.

What this looks like in CI numbers:

Without remote cache, every CI run is a cold build. With it, most PRs build in ~1 minute.

--mount=type=cache (Persistent Package Cache)

This is the BuildKit feature most people don't know about, and it's the single biggest build time win:

# ✅ Use BuildKit cache mounts for package managers
FROM node:20-alpine AS deps
WORKDIR /app

# Cache npm's global cache directory across builds
# This persists between CI runs (unlike the ephemeral container)
RUN --mount=type=cache,target=/root/.npm   npm ci --only=production

# For apt-get (when you absolutely must install system packages):
FROM python:3.12-slim
RUN --mount=type=cache,target=/var/cache/apt   apt-get update &&   apt-get install -y --no-install-recommends     libpq-dev     && rm -rf /var/lib/apt/lists/*

# For Go modules:
FROM golang:1.22-alpine AS build
WORKDIR /app
COPY go.mod go.sum ./
RUN --mount=type=cache,target=/go/pkg/mod   go mod download

The critical detail: These cache mounts survive the RUN command and are reused across builds on the same machine. Combined with remote registry cache, your CI runner's local disk acts as a hot cache, and the registry acts as a warm cache for fresh runners.

--secret (Don't Bake Secrets Into Layers)

# ❌ Antipattern — secret baked into image
FROM node:20-alpine
ARG NPM_TOKEN
RUN echo "//registry.npmjs.org/:_authToken=${NPM_TOKEN}" > ~/.npmrc
RUN npm ci --only=production
# That NPM_TOKEN is now in the layer history forever
RUN rm ~/.npmrc
# That's a NEW layer — old layer with the token is still there

# ✅ BuildKit secrets — never in layers
FROM node:20-alpine
RUN --mount=type=secret,id=npmrc,target=/root/.npmrc   npm ci --only=production

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

The secret is mounted as a tmpfs file during the build and discarded when the RUN command finishes. It never appears in any layer, not even in the build cache.

Antipattern #4: Not Pinning Base Image Digests

# ❌ Antipattern — version tag that moves
FROM node:20-alpine
# This could be node:20.0.0-alpine today,
# node:20.1.0-alpine tomorrow,
# or node:20.20.0-alpine in a month.

# Each update potentially introduces new CVEs,
# new behaviour, or (rarely) breaking changes.
# More importantly: two "identical" builds on different days
# produce different images.

The fix — pin by digest:

# ✅ Pinned — this exact image, forever
FROM node:20-alpine@sha256:1234abcd...
# Get the digest:
# docker pull node:20-alpine
# docker inspect node:20-alpine --format='{{index .RepoDigests 0}}'
# → node@sha256:1234abcd...

# For distroless:
FROM gcr.io/distroless/nodejs20-debian12@sha256:5678efgh...

"But now I never get security updates!" Correct. You get explicit updates when you choose to update the digest, not silent ones that might break your build on a Thursday afternoon.

Set up Dependabot or Renovate to watch your Dockerfiles and open PRs when base image digests change:

// .github/dependabot.yml
{
  "version": 2,
  "updates": [
    {
      "package-ecosystem": "docker",
      "directory": "/",
      "schedule": {
        "interval": "weekly"
      },
      "open-pull-requests-limit": 5
    }
  ]
}

When Renovate bumps the digest, CI runs, tests pass, image scans clean, and the change merges. You get the security update with exactly the same confidence as any other dependency change.

Antipattern #5: Running Package Manager Installs Without Cleanup

# ❌ Antipattern — installing then not cleaning up
FROM ubuntu:22.04
RUN apt-get update
RUN apt-get install -y curl wget git openssl ca-certificates
# All of apt's index files are still in the image:
# /var/lib/apt/lists/* — tens of megabytes

Every package manager stores its index/metadata. If you don't clean up, that metadata becomes permanent part of your image.

# ✅ Clean up in the same RUN command
FROM ubuntu:22.04
RUN apt-get update &&     apt-get install -y --no-install-recommends       curl       ca-certificates     && rm -rf /var/lib/apt/lists/*
# The rm runs in the SAME layer as the install,
# so the index files never persist to any layer.

# For Alpine (apk):
RUN apk add --no-cache curl ca-certificates
# --no-cache does exactly this — installs and discards index

The critical rule: Combine package install and cleanup in a single RUN command. Each RUN creates a separate layer. If you install in one and clean in the next, the first layer (with the index files) persists forever.

Antipattern #6: Fat Layers That Never Change

# ❌ Antipattern — all-or-nothing layers
RUN apt-get update &&     apt-get install -y       python3       python3-pip       curl       git       && rm -rf /var/lib/apt/lists/*

# That's one big layer. When you remove git from the list,
# Docker rebuilds the entire layer — even if python3 and curl haven't changed.

But wait — I just told you to combine installs into a single RUN. There's a tension here. Single RUN = less image size. Multiple RUNs = better cache granularity.

The rule of thumb: Group dependencies by churn frequency.

# ✅ Group by change frequency
# Layer 1: OS dependencies (change rarely)
RUN apt-get update &&     apt-get install -y --no-install-recommends       ca-certificates       curl       && rm -rf /var/lib/apt/lists/*

# Layer 2: Application dependencies (change monthly)
RUN apt-get update &&     apt-get install -y --no-install-recommends       python3       python3-pip       libpq-dev       && rm -rf /var/lib/apt/lists/*

# Layer 3: Build tools (change quarterly)
RUN apt-get update &&     apt-get install -y --no-install-recommends       build-essential       && rm -rf /var/lib/apt/lists/*

If you never change the OS dependencies, layer 1 is cached forever. If you add a Python package next month, only layer 2 rebuilds.

The same logic applies to npm install:

# ✅ Split production and dev dependencies
COPY package.json package-lock.json ./

# Layer 1: Production deps (cached unless package.json changes deps section)
RUN --mount=type=cache,target=/root/.npm   npm ci --only=production

# Layer 2: Dev deps (only for testing/linting stages)
RUN --mount=type=cache,target=/root/.npm   npm ci

If you never change production dependencies but add a new dev dependency, only the dev layer rebuilds.

Antipattern #7: Using the Same Dockerfile for Dev and Production

# ❌ Antipattern — one Dockerfile to rule them all
FROM node:20-alpine
WORKDIR /app
COPY . .
RUN npm ci
RUN npm run build
EXPOSE 3000
CMD ["node", "dist/index.js"]
# Production gets: source code, node_modules with devDeps,
# test files, .env files, the kitchen sink

The fix — multi-stage with distinct purposes:

# Dockerfile — production only

# Stage 1: Install production dependencies
FROM node:20-alpine@sha256:abc AS deps
WORKDIR /app
COPY package.json package-lock.json ./
RUN --mount=type=cache,target=/root/.npm   npm ci --only=production

# Stage 2: Build the application
FROM node:20-alpine@sha256:abc AS build
WORKDIR /app
COPY package.json package-lock.json ./
RUN --mount=type=cache,target=/root/.npm   npm ci
COPY . .
RUN npm run build

# Stage 3: Production runtime
FROM gcr.io/distroless/nodejs20-debian12@sha256:def
WORKDIR /app
COPY --from=deps /app/node_modules ./node_modules
COPY --from=build /app/dist ./dist
CMD ["dist/index.js"]

# Dockerfile.dev — development only
FROM node:20-alpine@sha256:abc
WORKDIR /app
# Don't copy anything — mount source as a volume
# Don't install deps separately — they'll be in node_modules from host
CMD ["npm", "run", "dev"]
# docker compose mounts source code and node_modules via volumes

You wouldn't run your production database config in development. Why would you run the same Dockerfile? They serve different purposes with different requirements (speed vs size, completeness vs minimalism).

Antipattern #8: Not Taking Advantage of Docker Ignore Context

# ❌ You need .dockerignore but also:
# docker build -t myapp . sends the entire project directory to the daemon
# If your project is 500 MB (node_modules, .git, etc.),
# the Docker daemon has to receive and process 500 MB before doing anything.

# ✅ Use a minimal build context or stdin
tar -czf - src/ package.json package-lock.json tsconfig.json   | docker build -t myapp -f Dockerfile -

# Or use BuildKit's explicit context:
docker buildx build   --build-context src=./src   --build-context deps=./deps   -t myapp .  # The root context is just the Dockerfile and config files

In CI, where the build context is loaded from a network-shared cache or git clone, shaving 500 MB of context transfer translates to real seconds saved.

The Production Dockerfile Template

Here's what we actually use. Adapt the language-specific parts, but the structure is universal:

# ============================================================
# Stage 1: Development dependencies (cached by package manager)
# ============================================================
FROM node:20-alpine@sha256:abc AS deps
WORKDIR /app
COPY package.json package-lock.json ./
RUN --mount=type=cache,target=/root/.npm   npm ci --only=production

# ============================================================
# Stage 2: Build (full toolchain, devDeps, compile step)
# ============================================================
FROM node:20-alpine@sha256:abc AS build
WORKDIR /app
COPY package.json package-lock.json ./
RUN --mount=type=cache,target=/root/.npm   npm ci
COPY . .
RUN npm run build

# ============================================================
# Stage 3: Production runtime (distroless, minimal surface)
# ============================================================
FROM gcr.io/distroless/nodejs20-debian12@sha256:def
WORKDIR /app
COPY --from=deps /app/node_modules ./node_modules
COPY --from=build /app/dist ./dist

ENV NODE_ENV=production
# Distroless images don't have a shell, so we use exec form directly
EXPOSE 8080
USER nobody
CMD ["dist/index.js"]

Key design decisions explained:

1. Deps and build are separate stages. If only source files change, the deps stage is cached and only the build stage rebuilds. If package.json changes, only the install command rebuilds (and only for the relevant stage).

1. Distroless runtime. No shell, no package manager, no compilers. The runtime image ships: your compiled code, your production dependencies, and the language runtime. That's it. Fewer CVEs, less attack surface, faster pulls.

1. USER nobody — distroless images ship with the nobody user. If your application doesn't need root, don't run as root. It's the single most impactful security change you can make in a Dockerfile.

1. Digest pinning. Every base image is pinned to a specific content hash. Updates happen via Dependabot PRs, not silent tag drift.

1. BuildKit cache mounts. npm ci benefits from the global npm cache being preserved between builds.

Before and After

One of the services we migrated was a Node.js API that handled order processing. Here's what the change looked like:

The migration took one engineer two hours. The security team stopped complaining about image scan results. The CI pipeline freed up ~4 minutes per PR. The image now pulls in under 5 seconds instead of 30.

The Rules to Follow

1. Use .dockerignore. It's the cheapest optimisation you'll ever make.
2. Separate dependency installs from code copies. Layer caching depends on this.
3. Use BuildKit. Enable it, use cache mounts, use remote cache.
4. Multi-stage builds are non-negotiable. Build large, run small.
5. Pin base image digests. Reproducible builds or you don't care about reliability.
6. Clean up after package installs. In the same RUN command.
7. Don't run as root. USER nobody or your application's dedicated user.
8. Use distroless for production. If your production image has a shell, justify it.

These aren't aspirational. They're the floor for any production container image. If your Dockerfile doesn't follow all eight, you're paying for it in build time, pull time, security risk, and developer frustration.

Conclusion

The Dockerfile is the most neglected piece of configuration in modern infrastructure. It's the first thing you write when setting up a project and the last thing you revisit. But it's also the single artifact that determines your CI build time, your production image security posture, and your deploy speed.

The fixes aren't complex. They're just not part of the default tutorial. FROM node:20 is convenient for a demo. For production, you need FROM gcr.io/distroless/nodejs20-debian12@sha256:def. COPY . . works for a hackathon. For a team shipping to production five times a day, you need multi-stage builds with explicit layer separation.

Start with the Dockerfile template above. Run docker build and measure the result. Then open your existing Dockerfiles and apply the same patterns one at a time. The first one will take an hour. The tenth one will take five minutes. And your CI pipeline will thank you for every one.

— Technical content team at Rrezvin