Claude Code × Docker — DevContainers, Multi-Stage Builds, and Production Deployment

claude "Create a multi-stage Dockerfile for a Next.js 15 app with:
- Build stage: node:22-alpine base
- Production stage: node:22-alpine (distroless optional)
- Non-root user for security
- Minimal setup using .next/standalone
- ARG to accept NODE_ENV"

# ──────────────────────────────────
# Stage 1: Install dependencies
# ──────────────────────────────────
FROM node:22-alpine AS deps
RUN apk add --no-cache libc6-compat
WORKDIR /app
 
# Copy only package files first (maximizes cache hits)
COPY package.json package-lock.json* ./
RUN npm ci --only=production --ignore-scripts
 
# ──────────────────────────────────
# Stage 2: Build
# ──────────────────────────────────
FROM node:22-alpine AS builder
WORKDIR /app
 
COPY --from=deps /app/node_modules ./node_modules
COPY . .
 
# Assumes output: 'standalone' is set in next.config.ts
ENV NEXT_TELEMETRY_DISABLED=1
RUN npm run build
 
# ──────────────────────────────────
# Stage 3: Production runner (minimal size)
# ──────────────────────────────────
FROM node:22-alpine AS runner
WORKDIR /app
 
ARG NODE_ENV=production
ENV NODE_ENV=${NODE_ENV}
ENV NEXT_TELEMETRY_DISABLED=1
ENV PORT=3000
 
# Security: create a non-root user
RUN addgroup --system --gid 1001 nodejs && \
    adduser --system --uid 1001 nextjs
 
# Copy only the files needed for standalone output
COPY --from=builder /app/public ./public
COPY --from=builder --chown=nextjs:nodejs /app/.next/standalone ./
COPY --from=builder --chown=nextjs:nodejs /app/.next/static ./.next/static
 
USER nextjs
 
EXPOSE 3000
 
HEALTHCHECK --interval=30s --timeout=10s --start-period=5s --retries=3 \
    CMD wget --no-verbose --tries=1 --spider http://localhost:3000/api/health || exit 1
 
CMD ["node", "server.js"]

# Build and check
docker build -t myapp:prod .
docker images myapp
 
# Expected output:
# REPOSITORY   TAG    IMAGE ID       CREATED         SIZE
# myapp        prod   a1b2c3d4e5f6   2 minutes ago   118MB

claude "Create a docker-compose.yml with:
- Next.js frontend + Hono.js API + PostgreSQL + Redis
- Volume mounts for hot reload
- Health checks for each service
- Environment variables loaded from .env.local
- Separate profiles for development and CI"

version: "3.9"
 
services:
  # ──── Frontend ────
  web:
    build:
      context: ./web
      dockerfile: Dockerfile.dev
      target: development
    ports:
      - "3000:3000"
    volumes:
      - ./web:/app
      - /app/node_modules  # Use container's node_modules
    environment:
      - NODE_ENV=development
      - NEXT_PUBLIC_API_URL=http://localhost:8080
    env_file:
      - ./web/.env.local
    depends_on:
      api:
        condition: service_healthy
    healthcheck:
      test: ["CMD", "wget", "--spider", "-q", "http://localhost:3000"]
      interval: 30s
      timeout: 10s
      retries: 3
 
  # ──── Backend API ────
  api:
    build:
      context: ./api
      dockerfile: Dockerfile.dev
    ports:
      - "8080:8080"
    volumes:
      - ./api:/app
      - /app/node_modules
    environment:
      - NODE_ENV=development
      - DATABASE_URL=postgresql://postgres:password@db:5432/myapp
      - REDIS_URL=redis://cache:6379
    depends_on:
      db:
        condition: service_healthy
      cache:
        condition: service_healthy
    healthcheck:
      test: ["CMD", "wget", "--spider", "-q", "http://localhost:8080/health"]
      interval: 10s
      timeout: 5s
      retries: 5
      start_period: 10s
 
  # ──── PostgreSQL ────
  db:
    image: postgres:16-alpine
    ports:
      - "5432:5432"
    environment:
      POSTGRES_USER: postgres
      POSTGRES_PASSWORD: password
      POSTGRES_DB: myapp
    volumes:
      - postgres_data:/var/lib/postgresql/data
      - ./db/init:/docker-entrypoint-initdb.d
    healthcheck:
      test: ["CMD-SHELL", "pg_isready -U postgres -d myapp"]
      interval: 5s
      timeout: 3s
      retries: 10
 
  # ──── Redis ────
  cache:
    image: redis:7-alpine
    ports:
      - "6379:6379"
    volumes:
      - redis_data:/data
    command: redis-server --appendonly yes
    healthcheck:
      test: ["CMD", "redis-cli", "ping"]
      interval: 5s
      timeout: 3s
      retries: 5
 
  # ──── DB Migration (CI profile only) ────
  migrate:
    build:
      context: ./api
    command: npm run db:migrate
    environment:
      - DATABASE_URL=postgresql://postgres:password@db:5432/myapp
    depends_on:
      db:
        condition: service_healthy
    profiles:
      - ci
 
volumes:
  postgres_data:
  redis_data:

# Start all services (hot reload enabled)
docker compose up -d
 
# View logs (all services)
docker compose logs -f
 
# View logs for a specific service
docker compose logs -f api
 
# Run DB migration
docker compose run --rm migrate
 
# Execute a command inside a container
docker compose exec api npm run db:seed
 
# Stop and clean up
docker compose down -v  # Also removes volumes

# When errors occur
docker compose logs api 2>&1 | claude "Analyze this error and tell me how to fix it"

# Check health status
docker compose ps
 
# Inspect health check details for a specific container
docker inspect --format='{{json .State.Health}}' myapp-db-1 | python3 -m json.tool

claude "My Node.js Docker container throws:
EACCES: permission denied on node_modules.
How should I fix the Dockerfile for a non-root user setup?"

# Check memory usage
docker stats --no-stream
 
# Run service with resource limits
docker compose up -d --scale api=3

claude "Create a GitHub Actions CI/CD workflow that:
- Builds and tests Docker images on push to main
- Pushes to GHCR and deploys to Cloud Run on tag push
- Uses caching to reduce build time
- Includes a Trivy security scan"

name: Build and Deploy
 
on:
  push:
    branches: [main]
    tags: ["v*"]
  pull_request:
    branches: [main]
 
env:
  REGISTRY: ghcr.io
  IMAGE_NAME: ${{ github.repository }}
 
jobs:
  # ──── Tests ────
  test:
    runs-on: ubuntu-latest
    services:
      postgres:
        image: postgres:16-alpine
        env:
          POSTGRES_PASSWORD: test
          POSTGRES_DB: testdb
        options: >-
          --health-cmd pg_isready
          --health-interval 10s
          --health-timeout 5s
          --health-retries 5
        ports:
          - 5432:5432
 
    steps:
      - uses: actions/checkout@v4
 
      - name: Setup Node.js
        uses: actions/setup-node@v4
        with:
          node-version: "22"
          cache: "npm"
 
      - name: Install dependencies
        run: npm ci
 
      - name: Run unit tests
        run: npm test
 
      - name: Run integration tests
        run: npm run test:integration
        env:
          DATABASE_URL: postgresql://postgres:test@localhost:5432/testdb
 
  # ──── Build & Push ────
  build-and-push:
    needs: test
    runs-on: ubuntu-latest
    if: github.event_name != 'pull_request'
    permissions:
      contents: read
      packages: write
 
    outputs:
      image-digest: ${{ steps.build.outputs.digest }}
      image-tag: ${{ steps.meta.outputs.tags }}
 
    steps:
      - uses: actions/checkout@v4
 
      - name: Set up QEMU (for multi-arch builds)
        uses: docker/setup-qemu-action@v3
 
      - name: Set up Docker Buildx
        uses: docker/setup-buildx-action@v3
 
      - name: Log in to GHCR
        uses: docker/login-action@v3
        with:
          registry: ${{ env.REGISTRY }}
          username: ${{ github.actor }}
          password: ${{ secrets.GITHUB_TOKEN }}
 
      - name: Extract Docker metadata
        id: meta
        uses: docker/metadata-action@v5
        with:
          images: ${{ env.REGISTRY }}/${{ env.IMAGE_NAME }}
          tags: |
            type=ref,event=branch
            type=semver,pattern={{version}}
            type=semver,pattern={{major}}.{{minor}}
            type=sha,prefix=sha-
 
      - name: Build and push
        id: build
        uses: docker/build-push-action@v5
        with:
          context: .
          platforms: linux/amd64,linux/arm64
          push: true
          tags: ${{ steps.meta.outputs.tags }}
          labels: ${{ steps.meta.outputs.labels }}
          cache-from: type=gha
          cache-to: type=gha,mode=max
 
  # ──── Security Scan ────
  security-scan:
    needs: build-and-push
    runs-on: ubuntu-latest
    steps:
      - name: Run Trivy vulnerability scanner
        uses: aquasecurity/trivy-action@master
        with:
          image-ref: ${{ needs.build-and-push.outputs.image-tag }}
          format: "sarif"
          output: "trivy-results.sarif"
          severity: "CRITICAL,HIGH"
 
      - name: Upload Trivy scan results
        uses: github/codeql-action/upload-sarif@v3
        with:
          sarif_file: "trivy-results.sarif"
 
  # ──── Deploy to Cloud Run (tags only) ────
  deploy:
    needs: [build-and-push, security-scan]
    runs-on: ubuntu-latest
    if: startsWith(github.ref, 'refs/tags/v')
    environment: production
 
    steps:
      - name: Authenticate to Google Cloud
        uses: google-github-actions/auth@v2
        with:
          credentials_json: ${{ secrets.GCP_SA_KEY }}
 
      - name: Deploy to Cloud Run
        uses: google-github-actions/deploy-cloudrun@v2
        with:
          service: myapp
          image: ${{ env.REGISTRY }}/${{ env.IMAGE_NAME }}@${{ needs.build-and-push.outputs.image-digest }}
          region: asia-northeast1
          flags: |
            --min-instances=1
            --max-instances=10
            --memory=512Mi
            --cpu=1

claude "Identify security issues in my current Dockerfile and
create a CIS benchmark-compliant version.
Focus on: non-root users, removing unnecessary packages, read-only filesystem."

RUN addgroup --gid 1001 appgroup && \
    adduser --uid 1001 --gid 1001 --disabled-password appuser
 
COPY --chown=appuser:appgroup . .
USER appuser

# Use distroless — no shell, no package manager, minimal attack surface
FROM gcr.io/distroless/nodejs22-debian12:nonroot AS runner

# docker-compose.yml
services:
  app:
    read_only: true
    tmpfs:
      - /tmp
      - /app/logs
    security_opt:
      - no-new-privileges:true
    cap_drop:
      - ALL

docker build \
  --secret id=api_key,env=API_KEY \
  -t myapp:prod .

# In Dockerfile — secret never lands in image layers or cache
RUN --mount=type=secret,id=api_key \
    API_KEY=$(cat /run/secrets/api_key) npm run build:with-key

# Scan with Trivy, then ask Claude Code to interpret results
trivy image myapp:prod --format json | \
  claude "Analyze this Trivy vulnerability report and list
  critical issues requiring immediate action, in priority order."

claude "Create Kubernetes manifests with:
- Deployment: 3 replicas, rolling update strategy
- Service: ClusterIP (Ingress-only access)
- HPA: scale out at 70% CPU (max 10 replicas)
- PodDisruptionBudget: always maintain minimum 2 replicas
- Resource requests and limits configured"

apiVersion: apps/v1
kind: Deployment
metadata:
  name: myapp
  namespace: production
  labels:
    app: myapp
    version: "1.0.0"
spec:
  replicas: 3
  selector:
    matchLabels:
      app: myapp
  strategy:
    type: RollingUpdate
    rollingUpdate:
      maxUnavailable: 1
      maxSurge: 1
  template:
    metadata:
      labels:
        app: myapp
    spec:
      securityContext:
        runAsNonRoot: true
        runAsUser: 1001
        fsGroup: 1001
      terminationGracePeriodSeconds: 60
      containers:
        - name: app
          image: ghcr.io/myorg/myapp:v1.0.0
          ports:
            - containerPort: 3000
          resources:
            requests:
              cpu: "100m"
              memory: "128Mi"
            limits:
              cpu: "500m"
              memory: "512Mi"
          livenessProbe:
            httpGet:
              path: /api/health
              port: 3000
            initialDelaySeconds: 10
            periodSeconds: 10
            failureThreshold: 3
          readinessProbe:
            httpGet:
              path: /api/ready
              port: 3000
            initialDelaySeconds: 5
            periodSeconds: 5
            successThreshold: 1
          securityContext:
            allowPrivilegeEscalation: false
            readOnlyRootFilesystem: true
            capabilities:
              drop:
                - ALL
          volumeMounts:
            - name: tmp-volume
              mountPath: /tmp
      volumes:
        - name: tmp-volume
          emptyDir: {}
 
---
apiVersion: autoscaling/v2
kind: HorizontalPodAutoscaler
metadata:
  name: myapp-hpa
  namespace: production
spec:
  scaleTargetRef:
    apiVersion: apps/v1
    kind: Deployment
    name: myapp
  minReplicas: 3
  maxReplicas: 10
  metrics:
    - type: Resource
      resource:
        name: cpu
        target:
          type: Utilization
          averageUtilization: 70
    - type: Resource
      resource:
        name: memory
        target:
          type: Utilization
          averageUtilization: 80
 
---
apiVersion: policy/v1
kind: PodDisruptionBudget
metadata:
  name: myapp-pdb
  namespace: production
spec:
  minAvailable: 2
  selector:
    matchLabels:
      app: myapp

claude "Create a fly.toml to deploy my Next.js app to Fly.io.
Tokyo region, 512MB memory, no auto-scaling (fixed 2 instances)."

# fly.toml
app = "myapp"
primary_region = "nrt"  # Tokyo
kill_signal = "SIGINT"
kill_timeout = "5s"
 
[build]
  dockerfile = "Dockerfile"
 
[env]
  PORT = "8080"
  NODE_ENV = "production"
 
[http_service]
  internal_port = 8080
  force_https = true
  auto_stop_machines = false
  auto_start_machines = true
  min_machines_running = 2
  
  [[http_service.checks]]
    grace_period = "10s"
    interval = "30s"
    method = "GET"
    path = "/api/health"
    timeout = "5s"
 
[[vm]]
  memory = "512mb"
  cpu_kind = "shared"
  cpus = 1

# Bulk-remove unused images and containers
docker system prune -af --volumes
 
# Ask Claude Code to analyze the root cause
df -h | claude "Analyze this disk usage and tell me
the best ways to reduce Docker-related file sizes."

# Check cache efficiency
docker build --progress=plain . 2>&1 | grep -E "CACHED|DONE"
 
# Common cause: COPY instruction order is not optimized
# Ask Claude Code to fix it:
claude "Improve the cache efficiency of this Dockerfile.
Optimize COPY instruction order to minimize rebuilds on code changes."

# Check for OOM events
docker events --filter event=oom
 
# Detailed memory usage
docker stats --no-stream --format "table {{.Name}}\t{{.MemUsage}}\t{{.MemPerc}}"
 
# Ask Claude Code for optimization guidance
claude "My Node.js Docker container OOMs at 512MB.
How should I tune --max-old-space-size and K8s resource limits?"