Node.js Docker Optimization FAQ & Answers

Multi-stage builds use multiple FROM statements in one Dockerfile, copying only necessary artifacts to final image. Reduces image size by 10x (70MB vs 700MB+). Pattern: Stage 1 (builder) installs all dependencies and builds app, Stage 2 (production) copies built artifacts and installs only production deps. Example: FROM node:18 AS builder (build stage), FROM node:18-alpine AS production (runtime stage). Benefits: (1) Build tools excluded from production (TypeScript compiler, testing frameworks, dev dependencies), (2) Source code excluded (only compiled output), (3) Smaller attack surface (fewer packages), (4) Faster deploys (smaller image). Production image contains: Built JavaScript, node_modules (production only), runtime files. Not: TypeScript source, tests, build tools, dev dependencies.

Alpine Linux produces smallest Node.js images: ~70MB vs ~900MB for standard node:18. Alpine is minimal Linux distribution using musl libc instead of glibc. Use node:18-alpine as base image. Benefits: (1) Smaller size (faster pulls, less storage, lower bandwidth costs), (2) Reduced attack surface (fewer packages = fewer vulnerabilities), (3) Faster startup times. Trade-offs: (1) Some native modules incompatible (need recompilation), (2) musl libc differences can cause subtle bugs, (3) apk package manager instead of apt-get. When to use: Most Node.js apps work fine on Alpine. When not to use: Apps with native dependencies that don't support Alpine (use node:18-slim instead, ~180MB). Pattern: FROM node:18-alpine AS production. Install additional packages: RUN apk add --no-cache python3 make g++.

Copy package.json and package-lock.json BEFORE copying application code to leverage layer caching. Pattern: COPY package*.json ./, RUN npm ci --only=production, COPY . . Order matters: Docker caches each instruction, rebuilds from first changed layer. If code changes but dependencies don't, npm ci layer reused from cache. Wrong order: COPY . . (copies everything), RUN npm ci (reinstalls on every code change). Right order: COPY package*.json, npm ci (only reinstalls if package files change), COPY . . (code changes don't trigger reinstall). Additional: (1) npm ci instead of npm install (faster, deterministic), (2) --only=production flag (skips dev deps), (3) .dockerignore to exclude node_modules. Result: Builds complete in seconds instead of minutes when only code changes.

.dockerignore excludes files from Docker context, reducing build time and image size. Essential entries: node_modules (huge, rebuilt during docker build), .git (source control not needed in image), .env (secrets shouldn't be in image), .log (logs), test/ (test files), .vscode/ .idea/ (IDE configs), README.md docs/ (documentation), Dockerfile .dockerignore (meta files). Pattern: Create .dockerignore: node_modules, npm-debug.log, .git, .gitignore, .env, .env., dist/ (if TypeScript, rebuild in Docker), coverage/ (test coverage). Why: node_modules can be 500MB+, copying to Docker context slows builds. Docker rebuilds node_modules via npm ci anyway. .git history not needed in production image. Result: Build context reduced from 1GB to 10MB.

NO, never run as root. Run as non-root user (node user) for security. Default node image includes 'node' user (UID 1000). Switch user: USER node before CMD. Pattern: FROM node:18-alpine, WORKDIR /app, COPY --chown=node:node . ., USER node, CMD ["node", "server.js"]. Security risk: Root user in container has root privileges on host (if container breakout occurs). Attacker gains root access to host system. Non-root user limits damage: Can't install packages, can't modify system files, can't bind to privileged ports (<1024). If app needs port 80: Use reverse proxy (nginx) or node capabilities, map external 80 to internal 3000: docker run -p 80:3000. Set user in docker-compose: user: "node". Verify: docker exec whoami should return 'node' not 'root'.

Combine multiple RUN commands with && to create single layer. Each RUN, COPY, ADD creates new layer. More layers = larger image. Bad: RUN apt-get update (layer 1), RUN apt-get install -y python3 (layer 2), RUN apt-get clean (layer 3). Good: RUN apt-get update && apt-get install -y python3 && apt-get clean (single layer). Pattern: Chain commands with && (execute sequentially), use \ for line continuation (readability). Example: RUN apk add --no-cache python3 make g++ \ && npm ci --only=production \ && npm cache clean --force. Benefits: Smaller image size (removes intermediate artifacts), faster builds (fewer layers to process). Note: COPY package*.json and COPY . . should stay separate (layer caching optimization). Only combine RUN commands that logically group together.

Multi-stage builds use multiple FROM statements in one Dockerfile, copying only necessary artifacts to final image. Reduces image size by 10x (70MB vs 700MB+). Pattern: Stage 1 (builder) installs all dependencies and builds app, Stage 2 (production) copies built artifacts and installs only production deps. Example: FROM node:18 AS builder (build stage), FROM node:18-alpine AS production (runtime stage). Benefits: (1) Build tools excluded from production (TypeScript compiler, testing frameworks, dev dependencies), (2) Source code excluded (only compiled output), (3) Smaller attack surface (fewer packages), (4) Faster deploys (smaller image). Production image contains: Built JavaScript, node_modules (production only), runtime files. Not: TypeScript source, tests, build tools, dev dependencies.

Alpine Linux produces smallest Node.js images: ~70MB vs ~900MB for standard node:18. Alpine is minimal Linux distribution using musl libc instead of glibc. Use node:18-alpine as base image. Benefits: (1) Smaller size (faster pulls, less storage, lower bandwidth costs), (2) Reduced attack surface (fewer packages = fewer vulnerabilities), (3) Faster startup times. Trade-offs: (1) Some native modules incompatible (need recompilation), (2) musl libc differences can cause subtle bugs, (3) apk package manager instead of apt-get. When to use: Most Node.js apps work fine on Alpine. When not to use: Apps with native dependencies that don't support Alpine (use node:18-slim instead, ~180MB). Pattern: FROM node:18-alpine AS production. Install additional packages: RUN apk add --no-cache python3 make g++.

Copy package.json and package-lock.json BEFORE copying application code to leverage layer caching. Pattern: COPY package*.json ./, RUN npm ci --only=production, COPY . . Order matters: Docker caches each instruction, rebuilds from first changed layer. If code changes but dependencies don't, npm ci layer reused from cache. Wrong order: COPY . . (copies everything), RUN npm ci (reinstalls on every code change). Right order: COPY package*.json, npm ci (only reinstalls if package files change), COPY . . (code changes don't trigger reinstall). Additional: (1) npm ci instead of npm install (faster, deterministic), (2) --only=production flag (skips dev deps), (3) .dockerignore to exclude node_modules. Result: Builds complete in seconds instead of minutes when only code changes.

.dockerignore excludes files from Docker context, reducing build time and image size. Essential entries: node_modules (huge, rebuilt during docker build), .git (source control not needed in image), .env (secrets shouldn't be in image), .log (logs), test/ (test files), .vscode/ .idea/ (IDE configs), README.md docs/ (documentation), Dockerfile .dockerignore (meta files). Pattern: Create .dockerignore: node_modules, npm-debug.log, .git, .gitignore, .env, .env., dist/ (if TypeScript, rebuild in Docker), coverage/ (test coverage). Why: node_modules can be 500MB+, copying to Docker context slows builds. Docker rebuilds node_modules via npm ci anyway. .git history not needed in production image. Result: Build context reduced from 1GB to 10MB.

NO, never run as root. Run as non-root user (node user) for security. Default node image includes 'node' user (UID 1000). Switch user: USER node before CMD. Pattern: FROM node:18-alpine, WORKDIR /app, COPY --chown=node:node . ., USER node, CMD ["node", "server.js"]. Security risk: Root user in container has root privileges on host (if container breakout occurs). Attacker gains root access to host system. Non-root user limits damage: Can't install packages, can't modify system files, can't bind to privileged ports (<1024). If app needs port 80: Use reverse proxy (nginx) or node capabilities, map external 80 to internal 3000: docker run -p 80:3000. Set user in docker-compose: user: "node". Verify: docker exec whoami should return 'node' not 'root'.

Combine multiple RUN commands with && to create single layer. Each RUN, COPY, ADD creates new layer. More layers = larger image. Bad: RUN apt-get update (layer 1), RUN apt-get install -y python3 (layer 2), RUN apt-get clean (layer 3). Good: RUN apt-get update && apt-get install -y python3 && apt-get clean (single layer). Pattern: Chain commands with && (execute sequentially), use \ for line continuation (readability). Example: RUN apk add --no-cache python3 make g++ \ && npm ci --only=production \ && npm cache clean --force. Benefits: Smaller image size (removes intermediate artifacts), faster builds (fewer layers to process). Note: COPY package*.json and COPY . . should stay separate (layer caching optimization). Only combine RUN commands that logically group together.