oring.

# docker-compose.yml
version: "3.9"
services:
  app:
    build:
      context: .
      dockerfile: Dockerfile
    restart: unless-stopped
    read_only: true
    tmpfs:
      - /tmp:noexec,nosuid,size=64m
    deploy:
      resources:
        limits:
          cpus: "0.5"
          memory: 256M
        reservations:
          cpus: "0.25"
          memory: 128M
    healthcheck:
      test: ["CMD", "node", "-e", "require('http').get('http://localhost:3000/health', r => process.exit(r.statusCode === 200 ? 0 : 1))"]
      interval: 30s
      timeout: 5s
      retries: 3
      start_period: 10s
    networks:
      - appnet
    volumes:
      - type: tmpfs
        target: /app/logs
        tmpfs:
          size: 32M
    environment:
      - NODE_ENV=production

networks:
  appnet:
    driver: bridge
    ipam:
      config:
        - subnet: 172.28.0.0/16

Architecture Decisions

• Immutability: Images are built once, promoted through environments, never patched. Updates require new images.
• Explicit Dependencies: npm ci locks versions. No npm install in production.
• Non-Root Execution: Distroless enforces USER nonroot. Mitigates container escape risks.
• Read-Only Rootfs + Tmpfs: Prevents runtime filesystem tampering. Logs/temp files use ephemeral memory mounts.
• Health-Driven Orchestration: Compose/Kubernetes restarts unhealthy containers automatically. No manual intervention.

Pitfall Guide

1. Running as Root: Containers inherit host kernel privileges. Root inside a container can exploit kernel vulnerabilities or escape namespaces. Always define USER and use non-privileged base images.
2. Ignoring Layer Caching: Copying COPY . . before dependency installation invalidates cache on every code change. Separate dependency installation from source code copying.
3. Bloating Images with Dev Tools: Including git, curl, vim, or test frameworks in production images increases pull time, storage costs, and CVE exposure. Use multi-stage builds.
4. Missing or Misconfigured Health Checks: Without health endpoints, orchestrators cannot distinguish between a hung process and a healthy one. Implement /health routes returning 200 only when dependencies (DB, cache, queues) are reachable.
5. Persistent State in Containers: Writing logs, uploads, or session data to the container filesystem violates immutability and prevents horizontal scaling. Externalize state to volumes, object storage, or managed services.
6. Hardcoding Secrets in Images: Environment variables baked into images survive container restarts and leak in image registries. Use Docker secrets, HashiCorp Vault, or cloud KMS with runtime injection.
7. Unbounded Resource Allocation: Containers without CPU/memory limits can starve host systems or sibling containers. Always set deploy.resources.limits matching application profiling data.

Production Bundle

Action Checklist

• Audit base images for CVEs using docker scout cves or Trivy
• Enforce non-root execution in every Dockerfile
• Implement HTTP/TCP health checks matching orchestrator expectations
• Set CPU and memory limits based on load testing, not defaults
• Mount / as read-only; use tmpfs or named volumes for writable paths
• Externalize secrets via runtime injection; never bake into images
• Sign images with Cosign/Notary and verify in CI/CD pipelines
• Configure JSON logging with structured fields for downstream aggregation

Decision Matrix

Configuration Template

Dockerfile (Production-Ready)

FROM node:20-slim AS builder
WORKDIR /app
COPY package*.json ./
RUN npm ci --omit=dev --ignore-scripts
COPY . .
RUN npm run build && npm prune --production

FROM gcr.io/distroless/nodejs20-debian12
WORKDIR /app
COPY --from=builder /app/dist ./dist
COPY --from=builder /app/node_modules ./node_modules
COPY --from=builder /app/package.json ./

ENV NODE_ENV=production
ENV NODE_OPTIONS="--max-old-space-size=192"
USER nonroot:nonroot
EXPOSE 3000

HEALTHCHECK --interval=30s --timeout=5s --start-period=15s --retries=3 \
  CMD node -e "const http=require('http'); http.get('http://localhost:3000/health', r => process.exit(r.statusCode===200?0:1)).on('error',()=>process.exit(1))"

CMD ["dist/index.js"]

docker-compose.yml (Hardened)

version: "3.9"
services:
  web:
    build: .
    restart: unless-stopped
    read_only: true
    tmpfs:
      - /tmp:noexec,nosuid,size=64m
      - /app/logs:size=32m
    deploy:
      resources:
        limits:
          cpus: "0.75"
          memory: 384M
        reservations:
          cpus: "0.25"
          memory: 128M
    healthcheck:
      test: ["CMD", "node", "-e", "require('http').get('http://localhost:3000/health', r => process.exit(r.statusCode===200?0:1)).on('error',()=>process.exit(1))"]
      interval: 30s
      timeout: 5s
      retries: 3
      start_period: 15s
    networks:
      - backend
    environment:
      - NODE_ENV=production
      - LOG_LEVEL=info
    secrets:
      - db_password

networks:
  backend:
    driver: bridge
    ipam:
      config:
        - subnet: 172.28.1.0/24

secrets:
  db_password:
    external: true

Quick Start Guide

1. Initialize Project Structure

   myapp/
   ├── src/
   ├── Dockerfile
   ├── docker-compose.yml
   └── package.json
   

2. Write the Dockerfile Use the production template above. Replace dist/index.js with your entry point. Ensure your app exposes a /health endpoint.

3. Build & Validate Locally

   docker build -t myapp:latest .
   docker run --rm -p 3000:3000 myapp:latest
   curl http://localhost:3000/health
   

   Verify non-root execution: docker exec <container> whoami → nonroot

4. Deploy with Compose

   docker compose up -d
   docker compose ps
   docker compose logs -f web
   

   Monitor health status: docker inspect --format='{{.State.Health.Status}}' <container>

Containerization is a discipline, not a tool. Enforce immutability, bound resources, externalize state, and validate health. The runtime will reward you with predictable deployments, rapid scaling, and minimal operational debt.