Docker Containerization: A Developer's Complete Guide

Containers have revolutionized how we build, ship, and run applications. Docker makes containerization accessible, but mastering it requires understanding the underlying concepts and best practices. AI can accelerate your Docker journey.

Why Containers?#

Containers solve the "works on my machine" problem by packaging applications with their dependencies:

Consistency: Same environment everywhere
Isolation: Applications don't interfere with each other
Portability: Run anywhere Docker runs
Efficiency: Share OS kernel, lighter than VMs

Dockerfile Fundamentals#

Basic Structure#

# Base image
FROM node:20-alpine

# Set working directory
WORKDIR /app

# Copy dependency files
COPY package*.json ./

# Install dependencies
RUN npm ci --only=production

# Copy application code
COPY . .

# Expose port
EXPOSE 3000

# Start command
CMD ["node", "server.js"]

Layer Optimization#

# ❌ Bad: Invalidates cache on any code change
FROM node:20-alpine
COPY . .
RUN npm install

# ✅ Good: Dependencies cached separately
FROM node:20-alpine
WORKDIR /app
COPY package*.json ./
RUN npm ci
COPY . .

Multi-Stage Builds#

Build and Runtime Separation#

# Build stage
FROM node:20-alpine AS builder
WORKDIR /app
COPY package*.json ./
RUN npm ci
COPY . .
RUN npm run build

# Production stage
FROM node:20-alpine AS production
WORKDIR /app
COPY --from=builder /app/dist ./dist
COPY --from=builder /app/node_modules ./node_modules
COPY package*.json ./

USER node
EXPOSE 3000
CMD ["node", "dist/server.js"]

Multiple Build Targets#

# Base stage
FROM node:20-alpine AS base
WORKDIR /app
COPY package*.json ./

# Development stage
FROM base AS development
RUN npm install
COPY . .
CMD ["npm", "run", "dev"]

# Test stage
FROM base AS test
RUN npm ci
COPY . .
CMD ["npm", "test"]

# Production stage
FROM base AS production
RUN npm ci --only=production
COPY . .
RUN npm run build
CMD ["node", "dist/server.js"]

Build specific target:

docker build --target development -t myapp:dev .
docker build --target production -t myapp:prod .

Docker Compose#

Development Environment#

# docker-compose.yml
version: '3.8'

services:
  app:
    build:
      context: .
      target: development
    ports:
      - "3000:3000"
    volumes:
      - .:/app
      - /app/node_modules
    environment:
      - NODE_ENV=development
      - DATABASE_URL=postgres://user:pass@db:5432/myapp
    depends_on:
      - db
      - redis

  db:
    image: postgres:15-alpine
    volumes:
      - postgres_data:/var/lib/postgresql/data
    environment:
      - POSTGRES_USER=user
      - POSTGRES_PASSWORD=pass
      - POSTGRES_DB=myapp

  redis:
    image: redis:7-alpine
    volumes:
      - redis_data:/data

volumes:
  postgres_data:
  redis_data:

Production Compose#

# docker-compose.prod.yml
version: '3.8'

services:
  app:
    image: myapp:${VERSION:-latest}
    deploy:
      replicas: 3
      resources:
        limits:
          cpus: '0.5'
          memory: 512M
    environment:
      - NODE_ENV=production
    healthcheck:
      test: ["CMD", "curl", "-f", "http://localhost:3000/health"]
      interval: 30s
      timeout: 10s
      retries: 3

Image Optimization#

Minimize Image Size#

# ❌ Large image (1GB+)
FROM node:20

# ✅ Alpine base (100MB)
FROM node:20-alpine

# ✅ Distroless for production (even smaller)
FROM gcr.io/distroless/nodejs20-debian11

Remove Unnecessary Files#

# .dockerignore
node_modules
npm-debug.log
.git
.gitignore
.env
*.md
tests/
coverage/
.nyc_output/

Security Scanning#

# Scan for vulnerabilities
docker scout cves myapp:latest

# Alternative: Trivy
trivy image myapp:latest

Container Security#

Run as Non-Root#

FROM node:20-alpine

# Create non-root user
RUN addgroup -g 1001 -S nodejs && \
    adduser -S nodejs -u 1001

WORKDIR /app
COPY --chown=nodejs:nodejs . .

# Switch to non-root user
USER nodejs

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

Read-Only Filesystem#

services:
  app:
    image: myapp:latest
    read_only: true
    tmpfs:
      - /tmp
      - /app/logs

Secret Management#

# Docker secrets (Swarm mode)
services:
  app:
    secrets:
      - db_password

secrets:
  db_password:
    external: true

Debugging Containers#

Interactive Shell#

# Running container
docker exec -it container_name sh

# New container from image
docker run -it --rm myapp:latest sh

Container Logs#

# Follow logs
docker logs -f container_name

# Last 100 lines
docker logs --tail 100 container_name

# With timestamps
docker logs -t container_name

Resource Usage#

# Real-time stats
docker stats

# Inspect container
docker inspect container_name

Health Checks#

Dockerfile Health Check#

HEALTHCHECK --interval=30s --timeout=10s --start-period=5s --retries=3 \
  CMD curl -f http://localhost:3000/health || exit 1

Application Health Endpoint#

app.get('/health', async (req, res) => {
  const health = {
    status: 'healthy',
    timestamp: new Date().toISOString(),
    checks: {}
  };

  // Check database
  try {
    await db.query('SELECT 1');
    health.checks.database = 'healthy';
  } catch (e) {
    health.checks.database = 'unhealthy';
    health.status = 'unhealthy';
  }

  // Check Redis
  try {
    await redis.ping();
    health.checks.redis = 'healthy';
  } catch (e) {
    health.checks.redis = 'unhealthy';
    health.status = 'unhealthy';
  }

  const statusCode = health.status === 'healthy' ? 200 : 503;
  res.status(statusCode).json(health);
});

CI/CD Integration#

GitHub Actions#

name: Build and Push

on:
  push:
    branches: [main]

jobs:
  build:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4

      - name: Set up Docker Buildx
        uses: docker/setup-buildx-action@v3

      - name: Login to Registry
        uses: docker/login-action@v3
        with:
          registry: ghcr.io
          username: ${{ github.actor }}
          password: ${{ secrets.GITHUB_TOKEN }}

      - name: Build and Push
        uses: docker/build-push-action@v5
        with:
          context: .
          push: true
          tags: ghcr.io/${{ github.repository }}:${{ github.sha }}
          cache-from: type=gha
          cache-to: type=gha,mode=max

Common Patterns#

Entrypoint Scripts#

#!/bin/sh
# docker-entrypoint.sh

# Wait for database
until pg_isready -h db -p 5432; do
  echo "Waiting for database..."
  sleep 2
done

# Run migrations
npm run migrate

# Start application
exec "$@"

COPY docker-entrypoint.sh /usr/local/bin/
RUN chmod +x /usr/local/bin/docker-entrypoint.sh
ENTRYPOINT ["docker-entrypoint.sh"]
CMD ["node", "server.js"]

Conclusion#

Docker containerization is essential for modern development. With proper Dockerfiles, multi-stage builds, and security practices, you can create efficient, secure containers that run consistently everywhere.

AI helps generate optimized Dockerfiles, debug container issues, and implement best practices. Start with simple containers, then add complexity as needed—compose for local development, optimized images for production.

Share this article