docker-containerization

Original source / Raw SKILL.md

---
name: docker-containerization
description: This skill should be used when containerizing applications with Docker, creating Dockerfiles, docker-compose configurations, or deploying containers to various platforms. Ideal for Next.js, React, Node.js applications requiring containerization for development, production, or CI/CD pipelines. Use this skill when users need Docker configurations, multi-stage builds, container orchestration, or deployment to Kubernetes, ECS, Cloud Run, etc.
---

# Docker Containerization Skill

## Overview

Generate production-ready Docker configurations for modern web applications, particularly Next.js and Node.js projects. This skill provides Dockerfiles, docker-compose setups, bash scripts for container management, and comprehensive deployment guides for various orchestration platforms.

## Core Capabilities

### 1. Dockerfile Generation

Create optimized Dockerfiles for different environments:

**Production** (`assets/Dockerfile.production`):
- Multi-stage build reducing image size by 85%
- Alpine Linux base (~180MB final image)
- Non-root user execution for security
- Health checks and resource limits

**Development** (`assets/Dockerfile.development`):
- Hot reload support
- All dev dependencies included
- Volume mounts for live code updates

**Nginx Static** (`assets/Dockerfile.nginx`):
- Static export optimization
- Nginx reverse proxy included
- Smallest possible footprint

### 2. Docker Compose Configuration

Multi-container orchestration with `assets/docker-compose.yml`:
- Development and production services
- Network and volume management
- Health checks and logging
- Restart policies

### 3. Bash Scripts for Container Management

**docker-build.sh** - Build images with comprehensive options:
```bash
./docker-build.sh -e prod -t v1.0.0
./docker-build.sh -n my-app --no-cache --platform linux/amd64
```

**docker-run.sh** - Run containers with full configuration:
```bash
./docker-run.sh -i my-app -t v1.0.0 -d
./docker-run.sh -p 8080:3000 --env-file .env.production
```

**docker-push.sh** - Push to registries (Docker Hub, ECR, GCR, ACR):
```bash
./docker-push.sh -n my-app -t v1.0.0 --repo username/my-app
./docker-push.sh -r gcr.io/project --repo my-app --also-tag stable
```

**docker-cleanup.sh** - Free disk space:
```bash
./docker-cleanup.sh --all --dry-run  # Preview cleanup
./docker-cleanup.sh --containers --images  # Clean specific resources
```

### 4. Configuration Files

- **`.dockerignore`**: Excludes unnecessary files (node_modules, .git, logs)
- **`nginx.conf`**: Production-ready Nginx configuration with compression, caching, security headers

### 5. Reference Documentation

**docker-best-practices.md** covers:
- Multi-stage builds explained
- Image optimization techniques (50-85% size reduction)
- Security best practices (non-root users, vulnerability scanning)
- Performance optimization
- Health checks and logging
- Troubleshooting guide

**container-orchestration.md** covers deployment to:
- Docker Compose (local development)
- Kubernetes (enterprise scale with auto-scaling)
- Amazon ECS (AWS-native orchestration)
- Google Cloud Run (serverless containers)
- Azure Container Instances
- Digital Ocean App Platform

Includes configuration examples, commands, auto-scaling setup, and monitoring.

## Workflow Decision Tree

### 1. What environment?
- **Development** → `Dockerfile.development` (hot reload, all dependencies)
- **Production** → `Dockerfile.production` (minimal, secure, optimized)
- **Static Export** → `Dockerfile.nginx` (smallest footprint)

### 2. Single or Multi-container?
- **Single** → Generate Dockerfile only
- **Multi** → Generate `docker-compose.yml` (app + database, microservices)

### 3. Which registry?
- **Docker Hub** → `docker.io/username/image`
- **AWS ECR** → `123456789012.dkr.ecr.region.amazonaws.com/image`
- **Google GCR** → `gcr.io/project-id/image`
- **Azure ACR** → `registry.azurecr.io/image`

### 4. Deployment platform?
- **Kubernetes** → See `references/container-orchestration.md` K8s section
- **ECS** → See ECS task definition examples
- **Cloud Run** → See deployment commands
- **Docker Compose** → Use provided compose file

### 5. Optimizations needed?
- **Image size** → Multi-stage builds, Alpine base
- **Build speed** → Layer caching, BuildKit
- **Security** → Non-root user, vulnerability scanning
- **Performance** → Resource limits, health checks

## Usage Examples

### Example 1: Containerize Next.js App for Production

**User**: "Containerize my Next.js app for production"

**Steps**:
1. Copy `assets/Dockerfile.production` to project root as `Dockerfile`
2. Copy `assets/.dockerignore` to project root
3. Build: `./docker-build.sh -e prod -n my-app -t v1.0.0`
4. Test: `./docker-run.sh -i my-app -t v1.0.0 -p 3000:3000 -d`
5. Push: `./docker-push.sh -n my-app -t v1.0.0 --repo username/my-app`

### Example 2: Development with Docker Compose

**User**: "Set up Docker Compose for local development"

**Steps**:
1. Copy `assets/Dockerfile.development` and `assets/docker-compose.yml` to project
2. Customize services in docker-compose.yml
3. Start: `docker-compose up -d`
4. Logs: `docker-compose logs -f app-dev`

### Example 3: Deploy to Kubernetes

**User**: "Deploy my containerized app to Kubernetes"

**Steps**:
1. Build and push image to registry
2. Review `references/container-orchestration.md` Kubernetes section
3. Create K8s manifests (deployment, service, ingress)
4. Apply: `kubectl apply -f deployment.yaml`
5. Verify: `kubectl get pods && kubectl logs -f deployment/app`

### Example 4: Deploy to AWS ECS

**User**: "Deploy to AWS ECS Fargate"

**Steps**:
1. Build and push to ECR
2. Review `references/container-orchestration.md` ECS section
3. Create task definition JSON
4. Register: `aws ecs register-task-definition --cli-input-json file://task-def.json`
5. Create service: `aws ecs create-service --cluster my-cluster --service-name app --desired-count 3`

## Best Practices

### Security
✅ Use multi-stage builds for production
✅ Run as non-root user
✅ Use specific image tags (not `latest`)
✅ Scan for vulnerabilities
✅ Never hardcode secrets
✅ Implement health checks

### Performance
✅ Optimize layer caching order
✅ Use Alpine images (~85% smaller)
✅ Enable BuildKit for parallel builds
✅ Set resource limits
✅ Use compression

### Maintainability
✅ Add comments for complex steps
✅ Use build arguments for flexibility
✅ Keep Dockerfiles DRY
✅ Version control all configs
✅ Document environment variables

## Troubleshooting

**Image too large (>500MB)**
→ Use multi-stage builds, Alpine base, comprehensive .dockerignore

**Build is slow**
→ Optimize layer caching, use BuildKit, review dependencies

**Container exits immediately**
→ Check logs: `docker logs container-name`
→ Verify CMD/ENTRYPOINT, check port conflicts

**Changes not reflecting**
→ Rebuild without cache, check .dockerignore, verify volume mounts

## Quick Reference

```bash
# Build
./docker-build.sh -e prod -t latest

# Run
./docker-run.sh -i app -t latest -d

# Logs
docker logs -f app

# Execute
docker exec -it app sh

# Cleanup
./docker-cleanup.sh --all --dry-run  # Preview
./docker-cleanup.sh --all            # Execute
```

## Integration with CI/CD

### GitHub Actions
```yaml
- run: |
    chmod +x docker-build.sh docker-push.sh
    ./docker-build.sh -e prod -t ${{ github.sha }}
    ./docker-push.sh -n app -t ${{ github.sha }} --repo username/app
```

### GitLab CI
```yaml
build:
  script:
    - chmod +x docker-build.sh
    - ./docker-build.sh -e prod -t $CI_COMMIT_SHA
```

## Resources

### Scripts (`scripts/`)
Production-ready bash scripts with comprehensive features:
- `docker-build.sh` - Build images (400+ lines, colorized output)
- `docker-run.sh` - Run containers (400+ lines, auto conflict resolution)
- `docker-push.sh` - Push to registries (multi-registry support)
- `docker-cleanup.sh` - Clean resources (dry-run mode, selective cleanup)

### References (`references/`)
Detailed documentation loaded as needed:
- `docker-best-practices.md` - Comprehensive Docker best practices (~500 lines)
- `container-orchestration.md` - Deployment guides for 6+ platforms (~600 lines)

### Assets (`assets/`)
Ready-to-use templates:
- `Dockerfile.production` - Multi-stage production Dockerfile
- `Dockerfile.development` - Development Dockerfile
- `Dockerfile.nginx` - Static export with Nginx
- `docker-compose.yml` - Multi-container orchestration
- `.dockerignore` - Optimized exclusion rules
- `nginx.conf` - Production Nginx configuration


---

## Referenced Files

> The following files are referenced in this skill and included for context.

### assets/docker-compose.yml

```yaml
version: '3.8'

services:
  # Next.js Application - Development
  app-dev:
    build:
      context: .
      dockerfile: Dockerfile.development
    container_name: nextjs-app-dev
    ports:
      - "3000:3000"
    volumes:
      - .:/app
      - /app/node_modules
      - /app/.next
    environment:
      - NODE_ENV=development
      - PORT=3000
    networks:
      - app-network
    restart: unless-stopped

  # Next.js Application - Production
  app-prod:
    build:
      context: .
      dockerfile: Dockerfile.production
    container_name: nextjs-app-prod
    ports:
      - "3001:3000"
    environment:
      - NODE_ENV=production
      - PORT=3000
    networks:
      - app-network
    restart: unless-stopped
    healthcheck:
      test: ["CMD", "node", "-e", "require('http').get('http://localhost:3000/api/health', (r) => {process.exit(r.statusCode === 200 ? 0 : 1)})"]
      interval: 30s
      timeout: 3s
      retries: 3
      start_period: 10s

  # Nginx Reverse Proxy (optional)
  nginx:
    image: nginx:alpine
    container_name: nginx-proxy
    ports:
      - "80:80"
      - "443:443"
    volumes:
      - ./nginx.conf:/etc/nginx/conf.d/default.conf:ro
      - ./ssl:/etc/nginx/ssl:ro
    depends_on:
      - app-prod
    networks:
      - app-network
    restart: unless-stopped

networks:
  app-network:
    driver: bridge

```

### references/container-orchestration.md

```markdown
# Container Orchestration Guide

This document covers deploying Dockerized Next.js applications to various orchestration platforms.

## Docker Compose

### Basic Setup

Docker Compose is ideal for:
- Local development environments
- Small-scale deployments
- Testing multi-container setups

### Production Example

```yaml
version: '3.8'

services:
  app:
    image: nextjs-app:latest
    container_name: nextjs-prod
    restart: unless-stopped
    ports:
      - "3000:3000"
    environment:
      - NODE_ENV=production
    healthcheck:
      test: ["CMD", "curl", "-f", "http://localhost:3000/api/health"]
      interval: 30s
      timeout: 10s
      retries: 3
      start_period: 40s
    networks:
      - app-network
    logging:
      driver: "json-file"
      options:
        max-size: "10m"
        max-file: "3"

networks:
  app-network:
    driver: bridge
```

### Commands

```bash
# Start services
docker-compose up -d

# View logs
docker-compose logs -f

# Scale services
docker-compose up -d --scale app=3

# Stop services
docker-compose down

# Rebuild and restart
docker-compose up -d --build
```

## Kubernetes (K8s)

### When to Use Kubernetes

Use Kubernetes for:
- Large-scale deployments (100+ containers)
- High availability requirements
- Complex microservices architectures
- Auto-scaling needs
- Multi-cloud deployments

### Deployment Configuration

```yaml
# deployment.yaml
apiVersion: apps/v1
kind: Deployment
metadata:
  name: nextjs-app
  labels:
    app: nextjs-app
spec:
  replicas: 3
  selector:
    matchLabels:
      app: nextjs-app
  template:
    metadata:
      labels:
        app: nextjs-app
    spec:
      containers:
      - name: nextjs
        image: nextjs-app:latest
        ports:
        - containerPort: 3000
        env:
        - name: NODE_ENV
          value: "production"
        resources:
          requests:
            memory: "256Mi"
            cpu: "250m"
          limits:
            memory: "512Mi"
            cpu: "500m"
        livenessProbe:
          httpGet:
            path: /api/health
            port: 3000
          initialDelaySeconds: 30
          periodSeconds: 10
        readinessProbe:
          httpGet:
            path: /api/health
            port: 3000
          initialDelaySeconds: 5
          periodSeconds: 5
```

### Service Configuration

```yaml
# service.yaml
apiVersion: v1
kind: Service
metadata:
  name: nextjs-service
spec:
  selector:
    app: nextjs-app
  ports:
    - protocol: TCP
      port: 80
      targetPort: 3000
  type: LoadBalancer
```

### Ingress Configuration

```yaml
# ingress.yaml
apiVersion: networking.k8s.io/v1
kind: Ingress
metadata:
  name: nextjs-ingress
  annotations:
    kubernetes.io/ingress.class: "nginx"
    cert-manager.io/cluster-issuer: "letsencrypt-prod"
spec:
  tls:
  - hosts:
    - app.example.com
    secretName: nextjs-tls
  rules:
  - host: app.example.com
    http:
      paths:
      - path: /
        pathType: Prefix
        backend:
          service:
            name: nextjs-service
            port:
              number: 80
```

### Kubernetes Commands

```bash
# Apply configurations
kubectl apply -f deployment.yaml
kubectl apply -f service.yaml
kubectl apply -f ingress.yaml

# Check status
kubectl get deployments
kubectl get pods
kubectl get services

# View logs
kubectl logs -f deployment/nextjs-app

# Scale deployment
kubectl scale deployment nextjs-app --replicas=5

# Update image
kubectl set image deployment/nextjs-app nextjs=nextjs-app:v2.0.0

# Rollback
kubectl rollout undo deployment/nextjs-app

# Delete resources
kubectl delete -f deployment.yaml
```

## Amazon ECS (Elastic Container Service)

### Task Definition

```json
{
  "family": "nextjs-app",
  "networkMode": "awsvpc",
  "requiresCompatibilities": ["FARGATE"],
  "cpu": "512",
  "memory": "1024",
  "containerDefinitions": [
    {
      "name": "nextjs",
      "image": "123456789012.dkr.ecr.us-east-1.amazonaws.com/nextjs-app:latest",
      "portMappings": [
        {
          "containerPort": 3000,
          "protocol": "tcp"
        }
      ],
      "environment": [
        {
          "name": "NODE_ENV",
          "value": "production"
        }
      ],
      "logConfiguration": {
        "logDriver": "awslogs",
        "options": {
          "awslogs-group": "/ecs/nextjs-app",
          "awslogs-region": "us-east-1",
          "awslogs-stream-prefix": "ecs"
        }
      },
      "healthCheck": {
        "command": [
          "CMD-SHELL",
          "curl -f http://localhost:3000/api/health || exit 1"
        ],
        "interval": 30,
        "timeout": 5,
        "retries": 3,
        "startPeriod": 60
      }
    }
  ]
}
```

### ECS Commands

```bash
# Register task definition
aws ecs register-task-definition --cli-input-json file://task-definition.json

# Create service
aws ecs create-service \
  --cluster my-cluster \
  --service-name nextjs-service \
  --task-definition nextjs-app:1 \
  --desired-count 3 \
  --launch-type FARGATE \
  --network-configuration "awsvpcConfiguration={subnets=[subnet-12345],securityGroups=[sg-12345]}"

# Update service
aws ecs update-service \
  --cluster my-cluster \
  --service nextjs-service \
  --task-definition nextjs-app:2

# Scale service
aws ecs update-service \
  --cluster my-cluster \
  --service nextjs-service \
  --desired-count 5
```

## Google Cloud Run

### Deployment

```bash
# Build and push to GCR
gcloud builds submit --tag gcr.io/PROJECT_ID/nextjs-app

# Deploy to Cloud Run
gcloud run deploy nextjs-app \
  --image gcr.io/PROJECT_ID/nextjs-app \
  --platform managed \
  --region us-central1 \
  --allow-unauthenticated \
  --memory 512Mi \
  --cpu 1 \
  --max-instances 10 \
  --set-env-vars NODE_ENV=production
```

### Cloud Run YAML

```yaml
# service.yaml
apiVersion: serving.knative.dev/v1
kind: Service
metadata:
  name: nextjs-app
spec:
  template:
    metadata:
      annotations:
        autoscaling.knative.dev/maxScale: '10'
        autoscaling.knative.dev/minScale: '1'
    spec:
      containers:
      - image: gcr.io/PROJECT_ID/nextjs-app
        ports:
        - containerPort: 3000
        env:
        - name: NODE_ENV
          value: production
        resources:
          limits:
            memory: 512Mi
            cpu: '1'
```

## Azure Container Instances (ACI)

### Deployment

```bash
# Create resource group
az group create --name myResourceGroup --location eastus

# Create container
az container create \
  --resource-group myResourceGroup \
  --name nextjs-app \
  --image myregistry.azurecr.io/nextjs-app:latest \
  --cpu 1 \
  --memory 1 \
  --registry-login-server myregistry.azurecr.io \
  --registry-username <username> \
  --registry-password <password> \
  --dns-name-label nextjs-app-unique \
  --ports 3000
```

## Digital Ocean App Platform

### App Spec

```yaml
# .do/app.yaml
name: nextjs-app
services:
- name: web
  github:
    repo: username/nextjs-app
    branch: main
    deploy_on_push: true
  dockerfile_path: Dockerfile.production
  http_port: 3000
  instance_count: 3
  instance_size_slug: basic-s
  env_vars:
  - key: NODE_ENV
    value: "production"
  health_check:
    http_path: /api/health
    initial_delay_seconds: 30
    period_seconds: 10
    timeout_seconds: 5
    success_threshold: 1
    failure_threshold: 3
```

## Comparison Matrix

| Platform | Best For | Complexity | Cost | Auto-Scaling |
|----------|----------|------------|------|--------------|
| Docker Compose | Dev/Small deployments | Low | Very Low | No |
| Kubernetes | Enterprise/Large scale | High | Medium | Yes |
| ECS | AWS ecosystem | Medium | Medium | Yes |
| Cloud Run | Serverless/Pay-per-use | Low | Low | Yes |
| ACI | Simple Azure deployments | Low | Medium | Limited |
| DO App Platform | Simple deployments | Low | Low | Yes |

## Auto-Scaling Configuration

### Kubernetes HPA

```yaml
apiVersion: autoscaling/v2
kind: HorizontalPodAutoscaler
metadata:
  name: nextjs-app-hpa
spec:
  scaleTargetRef:
    apiVersion: apps/v1
    kind: Deployment
    name: nextjs-app
  minReplicas: 2
  maxReplicas: 10
  metrics:
  - type: Resource
    resource:
      name: cpu
      target:
        type: Utilization
        averageUtilization: 70
  - type: Resource
    resource:
      name: memory
      target:
        type: Utilization
        averageUtilization: 80
```

### ECS Auto Scaling

```bash
# Register scalable target
aws application-autoscaling register-scalable-target \
  --service-namespace ecs \
  --resource-id service/my-cluster/nextjs-service \
  --scalable-dimension ecs:service:DesiredCount \
  --min-capacity 2 \
  --max-capacity 10

# Create scaling policy
aws application-autoscaling put-scaling-policy \
  --policy-name cpu-scaling-policy \
  --service-namespace ecs \
  --resource-id service/my-cluster/nextjs-service \
  --scalable-dimension ecs:service:DesiredCount \
  --policy-type TargetTrackingScaling \
  --target-tracking-scaling-policy-configuration \
    "TargetValue=70.0,PredefinedMetricSpecification={PredefinedMetricType=ECSServiceAverageCPUUtilization}"
```

## Load Balancing

### Nginx Load Balancer

```nginx
upstream nextjs_backend {
    least_conn;
    server app1:3000 weight=3;
    server app2:3000 weight=2;
    server app3:3000 weight=1;
}

server {
    listen 80;
    server_name app.example.com;

    location / {
        proxy_pass http://nextjs_backend;
        proxy_http_version 1.1;
        proxy_set_header Upgrade $http_upgrade;
        proxy_set_header Connection 'upgrade';
        proxy_set_header Host $host;
        proxy_cache_bypass $http_upgrade;
    }
}
```

## Monitoring & Logging

### Prometheus + Grafana (Kubernetes)

```yaml
# servicemonitor.yaml
apiVersion: monitoring.coreos.com/v1
kind: ServiceMonitor
metadata:
  name: nextjs-app
spec:
  selector:
    matchLabels:
      app: nextjs-app
  endpoints:
  - port: metrics
    interval: 30s
```

### ELK Stack (Elasticsearch, Logstash, Kibana)

```yaml
# docker-compose.yml
services:
  elasticsearch:
    image: docker.elastic.co/elasticsearch/elasticsearch:8.5.0
    environment:
      - discovery.type=single-node
    ports:
      - "9200:9200"

  logstash:
    image: docker.elastic.co/logstash/logstash:8.5.0
    volumes:
      - ./logstash.conf:/usr/share/logstash/pipeline/logstash.conf

  kibana:
    image: docker.elastic.co/kibana/kibana:8.5.0
    ports:
      - "5601:5601"
```

## Disaster Recovery

### Backup Strategies

1. **Container Images**: Store in multiple registries
2. **Data Volumes**: Regular snapshots
3. **Configuration**: Version control (Git)
4. **Secrets**: Encrypted backups

### High Availability

```yaml
# Kubernetes with pod anti-affinity
affinity:
  podAntiAffinity:
    requiredDuringSchedulingIgnoredDuringExecution:
    - labelSelector:
        matchExpressions:
        - key: app
          operator: In
          values:
          - nextjs-app
      topologyKey: kubernetes.io/hostname
```

---

**Last Updated**: November 2025
**Version**: 1.0.0

```