🧱 What is a Multi-Stage Build in Docker?

Multi-stage build allows you to use multiple FROM statements in a single Dockerfile to:

• Build the app in one stage 🏗️
• Copy only what's needed to a smaller final image 📦

❓ Why Do We Need It?

✅ Main Goals:

🧠 Real-World Analogy

Imagine:

• 🏗️ Stage 1 = Construction site (messy, heavy tools)
• 🏠 Stage 2 = Finished house (clean, cozy)

You build in the messy environment, but only move the furniture into the clean house. 🧹

🧪 Multi-Stage Build Syntax

# 🔨 Stage 1: Build Stage FROM node:20-alpine AS builder WORKDIR /app COPY package*.json ./ RUN npm ci COPY . . RUN npm run build # 📦 Stage 2: Final Production Image FROM node:20-alpine WORKDIR /app # Copy only final build artifacts (no source or node_modules) COPY --from=builder /app/dist ./dist COPY --from=builder /app/package.json ./ RUN npm ci --omit=dev # Set env vars, port and run ENV PORT=3000 EXPOSE 3000 CMD ["node", "dist/index.js"] 

🔍 Key Concepts Explained

📦 Before vs After: Image Size

💥 Real Project Example: React App

# Step 1: Build React App FROM node:20-alpine AS builder WORKDIR /app COPY package*.json ./ RUN npm install COPY . . RUN npm run build # Step 2: Serve using NGINX FROM nginx:alpine COPY --from=builder /app/build /usr/share/nginx/html EXPOSE 80 CMD ["nginx", "-g", "daemon off;"] 

✅ This builds the app with Node.js, and serves the static files via NGINX (no Node.js in final image!)

🎯 Common Multi-Stage Use Cases

🧰 Pro Tips & Best Practices

🔄 Combine with Docker Compose

You can define multi-stage builds in your Dockerfile and just run:

docker-compose build docker-compose up 

Your services will use the optimized final image automatically 🧠✅

🛠️ Example Multi-Stage for TypeScript API

# Stage 1: Compile TS FROM node:20-alpine AS builder WORKDIR /app COPY . . RUN npm install RUN npm run build # Stage 2: Run with only JS output FROM node:20-alpine WORKDIR /app COPY --from=builder /app/dist ./dist COPY --from=builder /app/package*.json ./ RUN npm ci --omit=dev CMD ["node", "dist/server.js"] 

✅ Summary: When to Use Multi-Stage Builds?

✅ Always use if:

• You're using build tools like tsc, webpack, vite
• You want minimal production images
• You want to separate testing/staging/building
• You want faster CI builds & smaller attack surface

🧾 Final TL;DR Cheatsheet

📦 Full Dockerfile (Context Recap)

FROM node:20-alpine3.19 as base # Stage 1: Build Stuff FROM base as builder WORKDIR /home/build COPY package*.json . COPY tsconfig.json . RUN npm install COPY src/ src/ RUN npm run build # Stage 2: Runner FROM base as runner WORKDIR /home/app COPY --from=builder /home/build/dist dist/ COPY --from=builder /home/build/package*.json . RUN npm install --omit=dev RUN addgroup --system --gid 1001 nodejs RUN adduser --system --uid 1001 nodejs USER nodejs EXPOSE 8000 ENV PORT=8000 CMD [ "npm", "start" ] 

🎯 A2Z Breakdown of Each Section

🧱 FROM node:20-alpine3.19 as base

🧠 What it does:

• Starts from a minimal Node.js 20 Alpine image
• Alpine is lightweight (~5MB), good for small, fast images
• as base names this stage for reuse

🧩 Think of base like a shared template that both stages use.

🔨 Stage 1: Builder

FROM base as builder WORKDIR /home/build 

🔧 What happens here:

• We switch to a new build stage, using base image
• WORKDIR /home/build sets a directory for our build process

COPY package*.json . COPY tsconfig.json . RUN npm install 

📦 Install dependencies:

• package*.json copied to install dependencies
• tsconfig.json is required for TypeScript compilation
• npm install installs all dependencies (dev + prod)

COPY src/ src/ RUN npm run build 

🛠️ Build your app:

• Copies your app's TypeScript code
• npm run build compiles TS into JS → typically inside /dist

✅ End Result of Stage 1:

A folder /home/build/dist with compiled production-ready JS output.

🚀 Stage 2: Runner

FROM base as runner WORKDIR /home/app 

📁 What it does:

• We now create a fresh container just for running the app.
• WORKDIR /home/app is where your app will run from.

COPY --from=builder /home/build/dist dist/ COPY --from=builder /home/build/package*.json . 

📂 Copy built artifacts only:

• Only copy the dist/ folder and package files (no source, no tsconfig)
• Ensures the final image is slim & clean

RUN npm install --omit=dev 

🔐 Production-only install:

• Installs only prod dependencies (no dev tools like eslint, tsc, etc.)
• Keeps final image light and secure ✅

👮 Add Secure Non-Root User

RUN addgroup --system --gid 1001 nodejs RUN adduser --system --uid 1001 nodejs USER nodejs 

🔐 Why?

• Running as root is dangerous in containers ❌
• We create a user nodejs with limited permissions for safety
• UID/GID 1001 is just an arbitrary non-root system user

🌐 Port & Env Setup

EXPOSE 8000 ENV PORT=8000 

• EXPOSE 8000: Documents that the app uses port 8000
• ENV PORT=8000: Sets the default port for app to use internally

You still need to use -p to map it to host:
docker run -p 8000:8000 <image>

🚦 Start the App

CMD [ "npm", "start" ] 

🟢 Default entrypoint when container runs

• This triggers your "start" script from package.json:

 "start": "node dist/index.js" 

✅ Summary Table

📊 Resulting Benefits

🧠 Bonus Tip: View Image Sizes

docker images 

Compare the multi-stage image (~100MB) vs a single-stage image (~400–600MB) 🤯

🔚 Final Thoughts

This approach follows Docker best practices:

• Multi-stage
• Production-ready
• Secure by default
• Reproducible builds