Docker Best Practices: Building Production-Ready Containers

Well-crafted Docker images are smaller, faster, and more secure. This guide covers best practices for building production-ready containers.

Multi-Stage Builds#

Node.js Application#

# Build stage
FROM node:20-alpine AS builder

WORKDIR /app

# Copy package files first (better layer caching)
COPY package.json pnpm-lock.yaml ./
RUN corepack enable && pnpm install --frozen-lockfile

# Copy source and build
COPY . .
RUN pnpm build

# Prune dev dependencies
RUN pnpm prune --prod

# Production stage
FROM node:20-alpine AS runner

WORKDIR /app

# Create non-root user
RUN addgroup --system --gid 1001 nodejs && \
    adduser --system --uid 1001 appuser

# Copy only production artifacts
COPY --from=builder --chown=appuser:nodejs /app/dist ./dist
COPY --from=builder --chown=appuser:nodejs /app/node_modules ./node_modules
COPY --from=builder --chown=appuser:nodejs /app/package.json ./

USER appuser

EXPOSE 3000

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

Go Application#

# Build stage
FROM golang:1.22-alpine AS builder

WORKDIR /app

# Download dependencies
COPY go.mod go.sum ./
RUN go mod download

# Build binary
COPY . .
RUN CGO_ENABLED=0 GOOS=linux go build -ldflags="-w -s" -o /app/server ./cmd/server

# Production stage - scratch for minimal image
FROM scratch

# Copy CA certificates for HTTPS
COPY --from=builder /etc/ssl/certs/ca-certificates.crt /etc/ssl/certs/

# Copy binary
COPY --from=builder /app/server /server

EXPOSE 8080

ENTRYPOINT ["/server"]

Layer Optimization#

Order Instructions by Change Frequency#

# Base image changes rarely
FROM node:20-alpine

WORKDIR /app

# System dependencies change rarely
RUN apk add --no-cache tini

# Package files change occasionally
COPY package.json pnpm-lock.yaml ./
RUN corepack enable && pnpm install --frozen-lockfile

# Source code changes frequently
COPY . .

RUN pnpm build

ENTRYPOINT ["/sbin/tini", "--"]
CMD ["node", "dist/index.js"]

Minimize Layer Count#

# Bad: Multiple RUN commands
RUN apt-get update
RUN apt-get install -y curl
RUN apt-get install -y git
RUN rm -rf /var/lib/apt/lists/*

# Good: Single RUN command
RUN apt-get update && \
    apt-get install -y --no-install-recommends \
      curl \
      git && \
    rm -rf /var/lib/apt/lists/*

Use .dockerignore#

# .dockerignore
node_modules
npm-debug.log
.git
.gitignore
.env
.env.*
Dockerfile
docker-compose*.yml
.dockerignore
README.md
.vscode
coverage
.nyc_output
dist
*.log

Security Hardening#

Run as Non-Root User#

FROM node:20-alpine

# Create app user
RUN addgroup -g 1001 -S appgroup && \
    adduser -u 1001 -S appuser -G appgroup

WORKDIR /app

COPY --chown=appuser:appgroup . .

# Switch to non-root user
USER appuser

CMD ["node", "index.js"]

Use Minimal Base Images#

# Instead of full images
FROM node:20           # ~1GB
FROM python:3.12       # ~1GB

# Use slim or alpine variants
FROM node:20-slim      # ~200MB
FROM node:20-alpine    # ~130MB
FROM python:3.12-slim  # ~150MB

# Or distroless for even smaller images
FROM gcr.io/distroless/nodejs20-debian12

Scan for Vulnerabilities#

# Build with security scanning
FROM node:20-alpine AS builder

# ... build steps ...

# Scan stage
FROM aquasec/trivy:latest AS scanner
COPY --from=builder /app /app
RUN trivy filesystem --exit-code 1 --severity HIGH,CRITICAL /app

# Final stage
FROM node:20-alpine
COPY --from=builder /app /app

Don't Store Secrets in Images#

# Bad: Secret in image
ENV API_KEY=secret123

# Good: Use runtime secrets
# docker run -e API_KEY=secret123 myapp

# Or use Docker secrets
# docker run --secret source=api_key,target=/run/secrets/api_key myapp

Health Checks#

FROM node:20-alpine

WORKDIR /app
COPY . .
RUN npm ci && npm run build

EXPOSE 3000

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

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

Handling Signals#

FROM node:20-alpine

# Use tini as init system
RUN apk add --no-cache tini

WORKDIR /app
COPY . .

# Tini handles signals properly
ENTRYPOINT ["/sbin/tini", "--"]
CMD ["node", "index.js"]

// Handle signals in your app
process.on('SIGTERM', () => {
  console.log('SIGTERM received, shutting down gracefully');
  server.close(() => {
    console.log('Server closed');
    process.exit(0);
  });
});

process.on('SIGINT', () => {
  console.log('SIGINT received, shutting down gracefully');
  server.close(() => {
    process.exit(0);
  });
});

Caching Dependencies#

Node.js with BuildKit Cache#

# syntax=docker/dockerfile:1
FROM node:20-alpine

WORKDIR /app

# Use BuildKit cache mount
RUN --mount=type=cache,target=/root/.npm \
    npm ci

COPY . .
RUN npm run build

Python with pip Cache#

# syntax=docker/dockerfile:1
FROM python:3.12-slim

WORKDIR /app

COPY requirements.txt .

# Cache pip downloads
RUN --mount=type=cache,target=/root/.cache/pip \
    pip install -r requirements.txt

COPY . .

Docker Compose for Development#

# docker-compose.yml
version: '3.8'

services:
  app:
    build:
      context: .
      dockerfile: Dockerfile.dev
    volumes:
      - .:/app
      - /app/node_modules  # Preserve node_modules
    ports:
      - "3000:3000"
    environment:
      - NODE_ENV=development
      - DATABASE_URL=postgres://postgres:password@db:5432/app
    depends_on:
      db:
        condition: service_healthy

  db:
    image: postgres:16-alpine
    environment:
      POSTGRES_PASSWORD: password
      POSTGRES_DB: app
    volumes:
      - postgres_data:/var/lib/postgresql/data
    healthcheck:
      test: ["CMD-SHELL", "pg_isready -U postgres"]
      interval: 5s
      timeout: 5s
      retries: 5

volumes:
  postgres_data:

Development Dockerfile#

# Dockerfile.dev
FROM node:20-alpine

WORKDIR /app

# Install development dependencies
RUN apk add --no-cache git

COPY package.json pnpm-lock.yaml ./
RUN corepack enable && pnpm install

# Don't copy source - use volume mount
EXPOSE 3000

CMD ["pnpm", "dev"]

Production Patterns#

Environment-Specific Builds#

# Use build arguments
ARG NODE_ENV=production

FROM node:20-alpine

ENV NODE_ENV=${NODE_ENV}

WORKDIR /app

COPY package.json pnpm-lock.yaml ./
RUN corepack enable && \
    if [ "$NODE_ENV" = "production" ]; then \
      pnpm install --frozen-lockfile --prod; \
    else \
      pnpm install --frozen-lockfile; \
    fi

COPY . .

RUN if [ "$NODE_ENV" = "production" ]; then pnpm build; fi

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

Labels and Metadata#

FROM node:20-alpine

LABEL org.opencontainers.image.source="https://github.com/myorg/myapp"
LABEL org.opencontainers.image.description="My Application"
LABEL org.opencontainers.image.version="1.0.0"
LABEL org.opencontainers.image.vendor="My Company"

# ... rest of Dockerfile

Debugging#

# Add debug tools to development image
FROM node:20-alpine AS base

FROM base AS development
RUN apk add --no-cache \
    curl \
    vim \
    htop

FROM base AS production
# Minimal production image

Common Mistakes#

1. Using Latest Tag#

# Bad: Unpredictable builds
FROM node:latest

# Good: Pin specific version
FROM node:20.11.0-alpine3.19

2. Running as Root#

# Bad: Default root user
FROM node:20-alpine
CMD ["node", "index.js"]

# Good: Explicit non-root user
FROM node:20-alpine
USER node
CMD ["node", "index.js"]

3. Not Cleaning Up#

# Bad: Leaves cache
RUN apt-get update && apt-get install -y curl

# Good: Clean up in same layer
RUN apt-get update && \
    apt-get install -y --no-install-recommends curl && \
    rm -rf /var/lib/apt/lists/*

Good Docker practices lead to smaller, faster, more secure containers. Use multi-stage builds, optimize layers, run as non-root, and scan for vulnerabilities. Your production containers should be minimal and immutable.