Multi-Stage Dockerfile Optimization: pnpm Cache Layers, Non-Root Users & Distroless

Architectural Foundations#

A naive single-stage Dockerfile for modern frontend applications yields bloated, insecure, and sluggish images. If dependency installation, TypeScript compilation, and server execution occur within a single container layer, the final artifact irrevocably inherits the entire filesystem overhead of the build environment: raw source code, compiler toolchains, package manager caches, and build scripts.

The Multi-Stage Build pattern fundamentally upends this paradigm. It decomposes the container lifecycle into four deterministic stages:

1. base: Defines the shared operating system configuration, pins the stable Node.js release, and activates the pnpm package manager via Corepack.
2. deps: A dedicated dependency cache layer. Project source files are intentionally excluded here, ensuring Docker caches this layer until pnpm-lock.yaml changes.
3. builder: The compilation context executing pnpm build. It produces the isolated output: 'standalone' bundle and compiles static client chunks.
4. runner: The final unprivileged production container, housing solely the Node.js runtime binary, a non-root system user, and the compiled server artifacts. Build tools and over 90% of development dependencies vanish from the final image.

[Multi-Stage Build Pipeline]

  ┌───────────────┐
  │  Stage: base  │ ──► node:22-alpine / glibc-compat / pnpm setup
  └───────┬───────┘
          │
          ├──────────────────────────────────┐
          ▼                                  ▼
  ┌───────────────┐                  ┌───────────────┐
  │  Stage: deps  │                  │ Stage: runner │
  │               │                  │               │
  │ • package.json│                  │ • non-root    │
  │ • lockfile    │                  │   nextjs:1001 │
  │ • pnpm cache  │                  │ • Distroless  │
  └───────┬───────┘                  │   or Alpine   │
          │ node_modules             └───────▲───────┘
          ▼                                  │
  ┌───────────────┐                          │ Copying
  │Stage: builder │                          │ production
  │               │                          │ artifacts
  │ • Source code │                          │
  │ • pnpm build  │ ─────────────────────────┘
  │ • standalone  │ ──► .next/standalone + static + public
  └───────────────┘

Coupled with the Docker BuildKit subsystem, multi-stage pipelines leverage Cache Mounts (--mount=type=cache). This technique mounts the global pnpm store directly from the host or CI runner without persisting package archives into intermediate Docker layers, accelerating repeat CI/CD builds by 5x to 10x.

Mental Model#

High-security, high-performance container engineering rests on two pillars: the Principle of Least Privilege and Attack Surface Reduction.

A container is not a full virtual machine; it is an isolated process running on the host Linux kernel, constrained by namespaces and cgroups. If a container process executes as root (UID 0), container breakout vulnerabilities or misconfigured volume mounts (-v /var/run/docker.sock) grant the adversary immediate root privileges over the underlying physical host.

To harden the production runtime, enterprise architectures apply two defensive standards:

1. Unprivileged User (Non-root user): Enforcing a designated system user with immutable IDs UID=1001 and GID=1001 (nextjs:nodejs), stripped of sudo privileges, OS modification capabilities, and privilege escalation (no-new-privileges).
2. Distroless Containers: Minimalist runtime images maintained by Google Container Tools (gcr.io/distroless/nodejs22). They contain only the Node.js runtime and vital dynamic C libraries (glibc, libssl). In Distroless images, the following are entirely eliminated:
   • Command shells (/bin/sh, /bin/bash).
   • Package managers (apt, apk).
   • Network utilities (curl, wget, nc).

[Comparing Conventional vs. Distroless Container Architecture]

Conventional Base (node:22 / Ubuntu / Alpine):
┌─────────────────────────────────────────────────────────────┐
│ Application (server.js, minimal node_modules)               │
├─────────────────────────────────────────────────────────────┤
│ Node.js Runtime (V8, libuv)                                 │
├─────────────────────────────────────────────────────────────┤
│ OS Utilities: sh, bash, apk, curl, tar, find, coreutils     │ ◄── Attack Vector (RCE)
├─────────────────────────────────────────────────────────────┤
│ OS Libraries: glibc/musl, libcrypto, ca-certificates        │
└─────────────────────────────────────────────────────────────┘

Distroless Base (gcr.io/distroless/nodejs22):
┌─────────────────────────────────────────────────────────────┐
│ Application (server.js, minimal node_modules)               │
├─────────────────────────────────────────────────────────────┤
│ Node.js Runtime (V8, libuv)                                 │
├─────────────────────────────────────────────────────────────┤
│ Core Libraries: glibc, libssl, ca-certificates              │
└─────────────────────────────────────────────────────────────┘
  (Shell binaries and package tools are physically non-existent)

If an attacker identifies a Remote Code Execution (RCE) vector in an npm dependency attempting system command injection, the exploit crashes instantly: the Linux kernel returns exec: "sh": executable file not found in $PATH.

Key containerization primitives:

• BuildKit Cache Mount (--mount=type=cache)
• Distroless Image
• UID/GID Mapping

Practical Applications#

1. Fintech & Payment Gateways (PCI-DSS & SOC2 Compliance)#

Regulatory compliance standards like PCI-DSS strictly forbid compilers (GCC, Python, Make) and package managers in production. Pairing Distroless with unprivileged users drops vulnerability scan reports (Trivy, Snyk) to zero open CVEs (0 Critical, 0 High), guaranteeing smooth CI/CD quality gate passes.

2. High-Frequency Deployment E-Commerce Platforms#

In teams shipping 40–60 production releases daily, BuildKit Cache Mounts compress pnpm install runtimes from 2.5 minutes down to 4 seconds. The package cache resides on the runner and only invalidates when the hash of pnpm-lock.yaml changes.

3. Edge Nodes & Constrained Storage Environments#

When deploying Next.js across edge nodes with restricted disk capacity, shrinking production images to 70–90 MB drastically reduces registry bandwidth consumption and optimizes node storage density.

How It Works#

To achieve maximum build throughput and enterprise-grade isolation, the multi-stage Dockerfile follows a strict architectural sequence:

1. Configuring pnpm Cache Mounts in BuildKit#

The pnpm package manager stores dependencies in a content-addressable store (store-dir). To leverage this inside Docker:

1. Declare the environment variable PNPM_HOME="/pnpm".
2. Add the cache mount flag --mount=type=cache,id=pnpm,target=/pnpm/store.
3. Set pnpm config set store-dir /pnpm/store.

Subsequent builds download only modified packages rather than re-fetching the entire dependency tree.

# syntax=docker/dockerfile:1.7

# ==============================================================================
# 1. BASE STAGE
# Standardized OS layer, environment variables, and corepack initialization
# ==============================================================================
FROM node:22-alpine AS base

ENV NODE_ENV=production \
    PNPM_HOME="/pnpm" \
    PATH="$PNPM_HOME:$PATH" \
    COREPACK_ENABLE_DOWNLOAD_PROMPT=0

WORKDIR /app

# libc6-compat is required for native Turbopack and Sharp compilation on Alpine
RUN apk add --no-cache libc6-compat && \
    corepack enable pnpm

# ==============================================================================
# 2. DEPS STAGE
# Isolated dependency installation with BuildKit store caching
# ==============================================================================
FROM base AS deps
WORKDIR /app

# Copy ONLY package manifests to preserve Docker layer caching
COPY package.json pnpm-lock.yaml* ./

# Mount host cache directory into pnpm store.
# Cache data is shared between builds without persisting into image layers!
RUN --mount=type=cache,id=pnpm,target=/pnpm/store \
    pnpm config set store-dir /pnpm/store && \
    pnpm install --frozen-lockfile --prod=false

# ==============================================================================
# 3. BUILDER STAGE
# Next.js compilation and standalone artifact generation
# ==============================================================================
FROM base AS builder
WORKDIR /app

# Copy resolved node_modules from deps stage
COPY --from=deps /app/node_modules ./node_modules
# Copy application source code
COPY . .

ENV NEXT_TELEMETRY_DISABLED=1 \
    NODE_ENV=production

# Mount the .next/cache compiler cache for fast incremental CI builds
RUN --mount=type=cache,id=nextcache,target=/app/.next/cache \
    pnpm build

# ==============================================================================
# 4. RUNNER STAGE (Target A: Hardened Alpine Linux)
# Minimal runtime layer with non-root security boundaries
# ==============================================================================
FROM node:22-alpine AS runner
WORKDIR /app

ENV NODE_ENV=production \
    PORT=3000 \
    HOSTNAME="0.0.0.0" \
    NEXT_TELEMETRY_DISABLED=1

# Establish unprivileged system user and group with deterministic UID/GID 1001
RUN addgroup --system --gid 1001 nodejs && \
    adduser --system --uid 1001 nextjs

# Pre-create directory for incremental ISR caching with write permissions for nextjs
RUN mkdir -p .next/cache && \
    chown -R nextjs:nodejs /app

# 1. Copy public static assets
COPY --from=builder --chown=nextjs:nodejs /app/public ./public

# 2. Copy the standalone server bundle
COPY --from=builder --chown=nextjs:nodejs /app/.next/standalone ./

# 3. Copy client-side hashed static chunks
COPY --from=builder --chown=nextjs:nodejs /app/.next/static ./.next/static

# Drop privileges to the non-root user
USER nextjs

EXPOSE 3000

# Launch standalone server directly with Node.js
CMD ["node", "server.js"]

# ==============================================================================
# RUNNER DISTROLESS ALTERNATIVE (Target B: Shell-less Zero Trust Security)
# Build target: docker build --target=runner-distroless -t app:distroless .
# ==============================================================================
FROM gcr.io/distroless/nodejs22-debian12:nonroot AS runner-distroless
WORKDIR /app

ENV NODE_ENV=production \
    PORT=3000 \
    HOSTNAME="0.0.0.0" \
    NEXT_TELEMETRY_DISABLED=1

# In Distroless, nonroot user (UID 65532) is predefined
COPY --from=builder --chown=nonroot:nonroot /app/public ./public
COPY --from=builder --chown=nonroot:nonroot /app/.next/standalone ./
COPY --from=builder --chown=nonroot:nonroot /app/.next/static ./.next/static

USER nonroot
EXPOSE 3000

# Distroless has no shell; CMD must strictly use the exec JSON array format:
CMD ["server.js"]

Common Pitfalls#

# ❌ ANTI-PATTERN: Copying entire repository before installing dependencies
COPY . .
RUN pnpm install

# ✅ CORRECT: Isolating package manifests into a dedicated cache layer
COPY package.json pnpm-lock.yaml ./
RUN pnpm install --frozen-lockfile
COPY . .

# ❌ INSECURE: Process runs as root
CMD ["node", "server.js"]

# ✅ CORRECT: Provisioning an unprivileged user and dropping privileges
RUN addgroup -S -g 1001 nodejs && adduser -S -u 1001 nextjs
USER nextjs
CMD ["node", "server.js"]

# ❌ INCORRECT: Shell form requires /bin/sh
CMD node server.js

# ✅ CORRECT: Strict Exec form JSON array
CMD ["server.js"]

# ❌ INCORRECT: .next directory owned by root; nextjs user cannot write
USER nextjs
CMD ["node", "server.js"]

# ✅ CORRECT: Explicitly pre-creating cache directories with proper ownership
RUN mkdir -p .next/cache && chown -R nextjs:nodejs /app/.next
USER nextjs
CMD ["node", "server.js"]

Interview Questions#