🪶 Image Optimization

Why Size Matters

An image is not just files on disk — it is something pushed to a registry, pulled onto every node in a cluster, and scanned for vulnerabilities on every build. Size multiplies across all of that.

The analogy is packing for a trip. The unoptimized traveler crams their entire wardrobe, every gadget, and a shelf of books into a giant suitcase "just in case." The optimized traveler packs only versatile essentials for the actual destination — a compact bag that is easy to carry and holds exactly what's needed. An optimized image is that carry-on.

• Faster deploys — a 120 MB image pulls in a fraction of the time of a 1 GB one, so rollouts and autoscaling are quicker.
• Lower cost — registry storage and cross-region transfer scale directly with size.
• Smaller attack surface — every compiler, shell, and unused package is one more thing a scanner flags and an attacker can exploit.
• Faster CI — smaller layers cache and transfer faster, tightening the feedback loop.

Choosing a Base Image

The base image is the single biggest lever on final size. Here is how the common Node bases compare.

Alpine: the pragmatic default

Alpine Linux swaps Debian's glibc for the smaller musl C library, cutting the OS footprint dramatically. It is the go-to production base for most Node apps. The one gotcha: packages with native C++ addons occasionally need build tools during install.

# Install native build deps, compile, then remove them — all in one layer
RUN apk add --no-cache --virtual .build python3 make g++ && \
    npm ci --omit=dev && \
    apk del .build

The --virtual .build trick groups the temporary packages under a label so apk del .build removes them cleanly once the compile is done.

Fewer, Leaner Layers

Recall from the Dockerfile lesson that each RUN adds a permanent layer. Crucially, deleting a file in a later layer does not shrink the image — the bytes still exist in the earlier layer beneath. So cleanup must happen in the same RUN that created the mess.

RUN apt-get update
RUN apt-get install -y build-essential
RUN rm -rf /var/lib/apt/lists/*   # too late — files persist in earlier layers

RUN apt-get update && \
    apt-get install -y --no-install-recommends build-essential && \
    rm -rf /var/lib/apt/lists/*

The same idea applies to npm: run the install and clean its cache together.

RUN npm ci --omit=dev && npm cache clean --force

Pruning Dependencies

For most Node apps, node_modules is the heaviest thing in the image. Two habits keep it lean:

1. Install production dependencies only

# npm ci is reproducible (uses package-lock.json); --omit=dev drops devDependencies
RUN npm ci --omit=dev

Your test frameworks, linters, TypeScript compiler, and bundler live in devDependencies. They are essential to build the app and useless to run it. In a multi-stage build you compile in the build stage (with all deps) and install only production deps in the runtime stage.

2. Prune the npm cache

RUN npm ci --omit=dev && npm cache clean --force

A thorough .dockerignore also keeps dependency and build junk out of the context entirely:

# .dockerignore
node_modules
.git
.env
.env.*
coverage
dist
build
*.md
*.log
.vscode
__tests__

Security & Health

A small image should also be a safe, observable one. Two low-effort additions pay off in production.

Run as a non-root user

If your base does not already provide one (Alpine's minimal image does not include the node user in every variant), create one and drop to it:

# Create a dedicated non-root user and give it the app directory
RUN addgroup -S nodejs && adduser -S -G nodejs nodejs
WORKDIR /app
COPY --chown=nodejs:nodejs . .
USER nodejs
CMD ["node", "index.js"]

If a process running as root is compromised, the attacker has root inside the container. Running as an unprivileged user contains the blast radius.

Add a health check

HEALTHCHECK --interval=30s --timeout=5s --start-period=10s --retries=3 \
    CMD node healthcheck.js

Docker and orchestrators use the HEALTHCHECK exit code to decide whether a container is actually serving traffic, not merely running. Keep the probe lightweight and have it verify real functionality — for example, that the HTTP server answers — rather than just that the process exists.

docker scout cves myapp:1.0     # built into Docker Desktop
trivy image myapp:1.0           # popular open-source scanner

Measuring & Analyzing

You cannot optimize what you do not measure. Two commands tell you where the bytes are.

docker history — bytes per layer

docker history --no-trunc myapp:1.0

This lists every layer with its size, so you can spot the expensive instruction — usually the dependency install — at a glance.

dive — an interactive layer explorer

dive opens an image layer by layer, shows exactly which files each one adds, and reports "wasted space" from files added in one layer and deleted in another.

$ dive myapp:1.0
Layers                              Size
FROM node:20-alpine                 5.0 MB
COPY package*.json ./               124 KB
RUN npm ci --omit=dev               42.5 MB
COPY . .                            3.2 MB

Image efficiency: 96%
Wasted space: 1.8 MB
Tip: a stray npm cache is inflating the deps layer.

Track these numbers over time: final image size, layer count, and vulnerability count. A trend line makes regressions obvious the moment a careless change doubles your image.

A Fully Optimized Image

Here is every technique from this lesson combined into one production Dockerfile for a Node.js API — multi-stage, Alpine runtime, prod-only deps, non-root user, and a health check.

# ================= Build stage =================
FROM node:20.11 AS build
WORKDIR /app
COPY package*.json ./
RUN npm ci
COPY . .
RUN npm run build

# ============ Production deps stage ============
FROM node:20.11-alpine AS deps
WORKDIR /app
COPY package*.json ./
RUN npm ci --omit=dev && npm cache clean --force

# ================ Runtime stage ================
FROM node:20.11-alpine
WORKDIR /app
ENV NODE_ENV=production

# Non-root user
RUN addgroup -S nodejs && adduser -S -G nodejs nodejs

# Slim, production-only node_modules + compiled output
COPY --from=deps  --chown=nodejs:nodejs /app/node_modules ./node_modules
COPY --from=build --chown=nodejs:nodejs /app/dist ./dist
COPY --chown=nodejs:nodejs package.json ./

USER nodejs

HEALTHCHECK --interval=30s --timeout=5s --retries=3 \
    CMD node healthcheck.js

EXPOSE 3000
CMD ["node", "dist/index.js"]

Practice & Quiz

FROM node:20
WORKDIR /app
COPY . .
RUN npm install
EXPOSE 3000
CMD ["node", "index.js"]

FROM node:20-alpine
ENV NODE_ENV=production
WORKDIR /app
COPY package*.json ./
RUN npm ci --omit=dev && npm cache clean --force
COPY --chown=node:node . .
USER node
EXPOSE 3000
CMD ["node", "index.js"]

Best Practices & Pitfalls

✅ Do

• Use the smallest base that meets your needs — alpine for most, distroless for hardened prod
• Combine related RUN commands and clean caches in the same step
• Install production-only deps (npm ci --omit=dev) in the runtime stage
• Run as a non-root USER and add a lightweight HEALTHCHECK
• Measure with docker history and dive; scan with Docker Scout or Trivy

❌ Don't

• Delete files in a later layer expecting the image to shrink
• Ship devDependencies, test files, or source maps to production
• Use temporary build tools without removing them (use Alpine's --virtual)
• Assume small equals secure — always scan for known CVEs

Summary

📚 Additional Resources

• Docker Docs — Building best practices
• Docker Docs — Docker Scout (image analysis)
• GoogleContainerTools — distroless base images

🚀 What's Next?

You can now build lean, secure single images. But real apps are several services at once — an API, a database, a cache. The next lesson, Docker Compose basics, shows how to define and run a whole multi-container stack from one file.