Distroless & Alpine Trade-offs

Choose a container base image based on libc compatibility, image size, and debuggability - not habit.

Recipe

Quick-reference recipe card - copy-paste ready.

# Default: Debian slim (glibc) - best npm compatibility
FROM node:24-bookworm-slim AS prod
WORKDIR /app
COPY package.json package-lock.json ./
RUN npm ci --omit=dev
COPY dist ./dist
USER node
CMD ["node", "dist/main.js"]

When to reach for this: Greenfield Node APIs with no native modules that require musl-specific builds. This is the team default.

Working Example

Three final-stage options for the same Express API:

# syntax=docker/dockerfile:1
 
FROM node:24-bookworm-slim AS build
WORKDIR /app
COPY package.json package-lock.json ./
RUN npm ci
COPY tsconfig.json src ./
RUN npm run build
 
# Option A: bookworm-slim (recommended default)
FROM node:24-bookworm-slim AS slim
WORKDIR /app
COPY package.json package-lock.json ./
RUN npm ci --omit=dev
COPY --from=build /app/dist ./dist
USER node
CMD ["node", "dist/main.js"]
 
# Option B: Alpine (smaller, musl)
FROM node:24-alpine AS alpine
WORKDIR /app
RUN apk add --no-cache libc6-compat
COPY package.json package-lock.json ./
RUN npm ci --omit=dev
COPY --from=build /app/dist ./dist
USER node
CMD ["node", "dist/main.js"]
 
# Option C: Distroless (minimal, no shell)
FROM gcr.io/distroless/nodejs24-debian12 AS distroless
WORKDIR /app
COPY --from=build /app/dist ./dist
COPY --from=slim /app/node_modules ./node_modules
USER nonroot
CMD ["dist/main.js"]

docker build --target slim -t api:slim .
docker build --target alpine -t api:alpine .
docker build --target distroless -t api:distroless .

What this demonstrates:

• Same compiled dist/ across all three runtimes
• Alpine may need libc6-compat for some prebuilt binaries
• Distroless copies node_modules from a glibc build stage (never compile inside distroless)

Deep Dive

libc: glibc vs musl

Node itself ships prebuilt binaries for glibc Linux. Alpine often forces npm rebuild or source compiles.

When Alpine Works

• Pure JavaScript dependencies only
• You control native deps and test npm ci on Alpine in CI
• Image size at registry matters (many edge pulls)

When Distroless Works

• Production API with no on-container debugging
• Security policy forbids shells and package managers in runtime
• You debug via logs, metrics, and ephemeral debug pods (K8s)

Debugging Trade-off

# bookworm-slim: shell available
docker run -it --entrypoint bash api:slim
 
# distroless: no shell - use debug pod or copy core dumps off-box
kubectl debug pod/api-xyz -it --image=busybox

Gotchas

• sharp on Alpine - common failure. Fix: use bookworm-slim or official sharp Alpine install docs with pinned versions.
• Building on Mac, running Alpine - architecture and libc mismatch. Fix: always docker build on Linux CI target.
• prisma generate in wrong stage - wrong OpenSSL bindings. Fix: generate in glibc build stage; copy artifacts.
• Distroless without USER nonroot - runs as root by default on some tags. Fix: explicit USER nonroot.
• Assuming smaller always means faster - musl allocator differs; benchmark your workload. Fix: load test before switching.
• Alpine apk in production Dockerfile - bloats layers. Fix: multi-stage; runtime has no package manager.

Alternatives

FAQs

Related

• Multi-Stage Builds - build on full image, run on minimal
• Image Slimming - size without musl risk
• Non-Root Containers - USER node / nonroot
• Docker Basics - first Dockerfile
• Docker Best Practices - section checklist

Stack versions: This page was written for Node.js 24.18.0 (Active LTS), npm 10+, TypeScript 5.6+, Express 5, Fastify 5, and NestJS 11.