Dockerizing a Node.js App in 2026: The Practical Guide

Containerize your app. Deploy anywhere. Never worry about "it works on my machine" again.

Why Docker?

Without Docker:
  Your machine → Node 22, Ubuntu, specific libraries
  Server → Node 18, Alpine, different glibc
  Colleague's Mac → Node 20, macOS, different everything
  → "Works on my machine!" 😤

With Docker:
  Everyone → Same OS, same Node version, same dependencies
  → Works everywhere! 🎉

The Basics

# Stage 1: Build
FROM node:22-alpine AS builder

WORKDIR /app

# Copy dependency files first (layer caching!)
COPY package*.json ./
RUN npm ci

# Copy source code
COPY . .
RUN npm run build

# Stage 2: Production (smaller image)
FROM node:22-alpine AS runner

WORKDIR /app

RUN addgroup -g 1001 appuser && \
    adduser -u 1001 -G appuser -s /bin/sh -D appuser

# Copy built files from builder stage
COPY --from=builder --chown=appuser:appuser /app/node_modules ./node_modules
COPY --from=builder --chown=appuser:appuser /app/dist ./dist
COPY --from=builder --chown=appuser:appuser /app/package.json ./package.json

USER appuser

EXPOSE 3000

CMD ["node", "dist/server.js"]

Key Concepts Explained

Multi-Stage Builds

# ❌ Bad: Single stage = big image with dev tools included
FROM node:22
WORKDIR /app
COPY . .
RUN npm install        # Installs ALL deps including devDependencies
RUN npm run build
CMD ["node", "server.js"]
# Image size: ~1.5GB (includes TypeScript, test frameworks, etc.)

# ✅ Good: Multi-stage = small production image
FROM node:22 AS build   # Has dev tools
→ npm install + build
FROM node:22-alpine     # Minimal runtime only
→ COPY --from=build    # Only copy what you need
# Image size: ~150MB (only runtime + your code)

Layer Caching

# Order matters! Docker caches each layer.

# ✅ Good order — changes rarely → put first
COPY package*.json ./       # Layer 1: Changes when deps change
RUN npm ci                  # Layer 2: Cached if package.json didn't change
COPY . .                    # Layer 3: Changes on every code edit
RUN npm run build           # Layer 4: Rebuilds only when source changes

# ❌ Bad order — invalidates cache too often
COPY . .                    # Changes every time you save a file!
RUN npm install             # Reinstalls deps every time (slow!)
RUN npm run build

.dockerignore

# Like .gitignore for Docker — reduces context size
node_modules
npm-debug.log
dist
.git
.env
.env.local
coverage
.vscode
.idea
*.md
Dockerfile*
docker-compose*

docker-compose.yml for Development

version: '3.8'

services:
  app:
    build:
      context: .
      dockerfile: Dockerfile.dev
    ports:
      - '3000:3000'
    volumes:
      # Hot reload: map local files into container
      - .:/app
      - /app/node_modules  # Use container's node_modules
    environment:
      - NODE_ENV=development
      - DATABASE_URL=postgres://postgres:password@db:5432/myapp
      - REDIS_URL=redis://redis:6379
    depends_on:
      db:
        condition: service_healthy
      redis:
        condition: service_healthy

  db:
    image: postgres:16-alpine
    environment:
      POSTGRES_USER: postgres
      POSTGRES_PASSWORD: password
      POSTGRES_DB: myapp
    ports:
      - '5432:5432'
    volumes:
      - pgdata:/var/lib/postgresql/data
    healthcheck:
      test: ['CMD-SHELL', 'pg_isready -U postgres']
      interval: 5s
      timeout: 5s
      retries: 5

  redis:
    image: redis:7-alpine
    ports:
      - '6379:6379'
    volumes:
      - redisdata:/data
    healthcheck:
      test: ['CMD', 'redis-cli', 'ping']
      interval: 5s

volumes:
  pgdata:
  redisdata:

Development Dockerfile

# Dockerfile.dev — optimized for development
FROM node:22-alpine

WORKDIR /app

# Install dev tools needed for hot reload
RUN npm install -g nodemon

# Copy deps first (cached layer)
COPY package*.json ./
RUN npm ci

# Don't copy source here — use volume mount instead

EXPOSE 3000

CMD ["nodemon", "--legacy-watch", "server.js"]
# --legacy-watch: fixes file watching in mounted volumes

Useful Commands

# Build and run
docker-compose up --build          # Build + start all services
docker-compose up -d                # Start in background
docker-compose down                 # Stop and remove containers
docker-compose logs -f app          # Follow app logs
docker-compose exec app sh          # Shell into container
docker-compose exec db psql -U postgres  # Connect to Postgres

# One-off commands
docker-compose exec app npm run migrate
docker-compose exec app npm run seed
docker-compose exec app npx jest

# Cleanup (when things get weird)
docker system prune -a              # Remove unused images/containers/volumes
docker compose down -v              # Remove volumes too (resets DB!)

# Debug container
docker run -it --rm myimage sh      # Interactive shell
docker logs <container_id>         # View logs
docker stats                       # Resource usage of running containers

Production Tips

# Production optimizations
FROM node:22-alpine

# Security: Run as non-root user
RUN addgroup -g 1001 app && \
    adduser -u 1001 -G app -s /bin/sh -D app

# Health check
HEALTHCHECK --interval=30s --timeout=3s \
  CMD wget --no-verbose --tries=1 --spider http://localhost:3000/health || exit 1

# Set Node to production mode
ENV NODE_ENV=production

# Optimize Node.js memory
ENV NODE_OPTIONS="--max-old-space-size=512"

WORKDIR /app
COPY --from=builder --chown=app:app ./dist ./dist
COPY --from=builder --chown=app:app ./node_modules ./node_modules
COPY --from=builder --chown=app:app ./package.json ./package.json

USER app

EXPOSE 3000

# Graceful shutdown
STOPSIGNAL SIGTERM

CMD ["node", "dist/server.js"]

Quick Reference Card

Command	Purpose
docker build -t myapp .	Build image
docker run -p 3000:3000 myapp	Run container
docker-compose up	Start all services
docker-compose down	Stop all services
docker ps	List running containers
docker images	List images
docker logs <id>	Container logs
docker exec -it <id> sh	Shell into container
docker system prune	Clean up unused resources

---

Are you using Docker in development or just production?

Follow @armorbreak for more DevOps content.