Docker Templates

Multi-stage Build Pattern

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

# Production stage
FROM node:20-alpine AS production
WORKDIR /app

# Security: Non-root user
RUN addgroup -g 1001 -S nodejs && \
    adduser -S nextjs -u 1001

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

USER nextjs
EXPOSE 3000

# 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/server.js"]

Docker Security Best Practices

| Practice | Implementation | |----------|----------------| | Non-root user | USER nodejs after setup | | Minimal base image | Use -alpine variants | | No secrets in image | Use runtime env vars | | Pin versions | FROM node:20.10.0-alpine | | .dockerignore | Exclude node_modules, .git, .env | | Read-only filesystem | --read-only flag when possible | | Resource limits | Set memory/CPU limits |

Docker Compose Patterns

version: '3.8'

services:
  app:
    build:
      context: .
      dockerfile: Dockerfile
      target: production
    ports:
      - "3000:3000"
    environment:
      - NODE_ENV=production
      - DATABASE_URL=${DATABASE_URL}
    depends_on:
      db:
        condition: service_healthy
    restart: unless-stopped
    healthcheck:
      test: ["CMD", "wget", "-q", "--spider", "http://localhost:3000/health"]
      interval: 30s
      timeout: 10s
      retries: 3

  db:
    image: postgres:15-alpine
    environment:
      - POSTGRES_USER=${DB_USER}
      - POSTGRES_PASSWORD=${DB_PASSWORD}
      - POSTGRES_DB=${DB_NAME}
    volumes:
      - postgres_data:/var/lib/postgresql/data
    healthcheck:
      test: ["CMD-SHELL", "pg_isready -U ${DB_USER}"]
      interval: 10s
      timeout: 5s
      retries: 5

volumes:
  postgres_data:

Image Size Targets

| App Type | Target Size | Strategy | |----------|-------------|----------| | Python API | < 200MB | python:3.12-slim + multi-stage | | Node.js API | < 150MB | node:20-alpine + multi-stage | | Go binary | < 50MB | golang:1.21-alpine build, scratch runtime |

Health Check Configuration

| Setting | Recommended | |---------|-------------| | Interval | 30s | | Timeout | 10s | | Retries | 3 | | Start period | 30s |

Return 200 for healthy, 503 for unhealthy. Keep checks lightweight.

Environment Variable Hierarchy

1. Runtime environment variables (highest priority)
2. .env file
3. docker-compose.yml defaults
4. Dockerfile ENV defaults (lowest)

Provide .env.example with placeholders (committed). Never commit .env files with secrets.

Resource Limits

| Resource | Development | Production | |----------|-------------|------------| | Memory | 512MB | Based on app profiling | | CPU | 0.5 | Based on app profiling |

Always set memory limits. Log to stdout/stderr, never to files inside containers.

Bundled References

Usable templates in references/ based on actual project patterns:

| File | Description | |------|-------------| | references/Dockerfile.react | React + nginx multi-stage build (node:22-alpine build, nginx:alpine prod) | | references/Dockerfile.python | FastAPI multi-stage build (python:3.11-slim, uvicorn) | | references/docker-compose.example.yml | Minimal FastAPI + Postgres + Redis stack |

Copy and adapt these templates for new services. All include health checks, non-root users, and alpine base images.

Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: komluk
• Source: komluk/scaffolding
• License: MIT

Install and usage instructions live in the source repository linked above.