Articles/Claude Code

⟐ Claude Code/2026-04-09Advanced

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

A practical guide to production-grade development workflows combining Claude Code and Docker. From DevContainer setup and multi-stage build optimization to GitHub Actions CI/CD and Kubernetes deployment — with practical code examples throughout.

Claude Code²⁰² Docker⁵ DevContainer CI/CD¹⁸ Kubernetes Production²³

✦ Premium Article

Container technology is an essential part of modern software development. Yet many developers still struggle with questions like "How should I structure my Dockerfile?", "DevContainer configuration is too complex", or "I keep running into issues when moving to production."

Claude Code dramatically solves these Docker-related challenges. You can ask it to optimize your Dockerfile in natural language, paste error messages directly and let it diagnose the cause, or automate the generation of complex Kubernetes YAML.

Below is a production-grade development and deployment workflow built from Claude Code and Docker, step by step, with real code. DevContainer setup, multi-stage builds, Docker Compose for local development, GitHub Actions CI/CD, and production deployment to Kubernetes or Fly.io.

This guide is designed for intermediate-to-advanced engineers who have basic Docker knowledge but haven't yet taken the leap into production operations. With Claude Code, you'll compress work that used to take days into hours.

DevContainer × Claude Code — Build a Reproducible Dev Environment in 5 Minutes

What Is DevContainer?

DevContainer is a mechanism used with VS Code or GitHub Codespaces that lets you define your development environment as code. Every team member works in an identical environment, eliminating the classic "it works on my machine" problem.

With Claude Code, you can generate and optimize .devcontainer/devcontainer.json files using natural language.

Generating a DevContainer with Claude Code

Run the following from your project root:

# Example Claude Code request
claude "Create a devcontainer.json for a project using Node.js 22 + TypeScript + PostgreSQL 16.
Also run npm install in the postCreateCommand."

Example generated .devcontainer/devcontainer.json:

{
  "name": "Node.js + TypeScript + PostgreSQL",
  "dockerComposeFile": "docker-compose.yml",
  "service": "app",
  "workspaceFolder": "/workspace",
  "features": {
    "ghcr.io/devcontainers/features/node:1": {
      "version": "22"
    },
    "ghcr.io/devcontainers/features/git:1": {},
    "ghcr.io/devcontainers/features/github-cli:1": {}
  },
  "customizations": {
    "vscode": {
      "extensions": [
        "dbaeumer.vscode-eslint",
        "esbenp.prettier-vscode",
        "ms-vscode.vscode-typescript-next",
        "bradlc.vscode-tailwindcss"
      ],
      "settings": {
        "editor.formatOnSave": true,
        "editor.defaultFormatter": "esbenp.prettier-vscode"
      }
    }
  },
  "postCreateCommand": "npm install",
  "remoteUser": "node",
  "forwardPorts": [3000, 5432],
  "portsAttributes": {
    "3000": { "label": "App Server", "onAutoForward": "notify" },
    "5432": { "label": "PostgreSQL", "onAutoForward": "silent" }
  }
}

Solving Common DevContainer Issues with Claude Code

If your DevContainer won't start, paste the error message directly into Claude Code:

claude "My DevContainer won't start with this error. Please identify the cause and fix:
[error] failed to solve: failed to read dockerfile: open .devcontainer/Dockerfile: no such file or directory"

Claude Code will immediately identify the problem and propose either generating the missing Dockerfile or fixing the devcontainer.json.

Multi-Stage Builds — Minimizing Your Production Image

Why Multi-Stage Builds Matter

A Node.js app packaged naively into Docker — including node_modules — can easily reach several gigabytes. Production environments need lightweight images containing only the built artifacts.

Multi-stage builds separate the build environment from the runtime environment, reducing production images to under 100MB.

Generating a Multi-Stage Dockerfile with Claude Code

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"

Example generated Dockerfile:

# ──────────────────────────────────
# 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"]

This Dockerfile keeps the final image size to approximately 80–120MB — about a 90% reduction compared to a development image that includes node_modules.

Verifying Image Size

# 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

✦

Thank you for reading this far.

Continue Reading

What follows includes implementation code, benchmarks, and practical content we hope you'll find useful. This site runs without ads — server and development costs are supported entirely by members like you. If it's been helpful, we'd be truly grateful for your support.

WHAT YOU'LL LEARN

✦If you've been stuck on DevContainer configuration, you'll be able to set up a seamless Claude Code integration environment starting today

✦You'll learn multi-stage builds, Docker Compose, and security hardening patterns that you can apply directly to your own projects

✦You'll be able to eliminate manual deployment work by building a GitHub Actions × Docker × Claude Code automation pipeline

Secure payment via Stripe · Cancel anytime

✦

Unlock This Article

Get full access to the rest of this article. Buy once, read anytime. This site is ad-free — your support goes directly toward keeping it running.

Unlock all articles with Membership →

Docker Compose — Building a Local Multi-Service Development Environment

Designing a Practical docker-compose.yml

Ask Claude Code to build a full-stack dev environment with a frontend, backend API, database, and Redis:

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"

Generated docker-compose.yml:

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:

Development Workflow with Docker Compose

# 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

Debugging Containers with Claude Code — Solve Problems 10x Faster

Error-by-Error Troubleshooting

Pipe container logs directly to Claude Code for instant analysis:

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

Common problems and how Claude Code helps solve them:

Problem 1: Port binding error

Error response from daemon: driver failed programming external connectivity:
Bind for 0.0.0.0:5432 failed: port is already allocated

Claude Code immediately proposes how to identify the conflicting process (lsof -i :5432) and suggests updating the port in docker-compose.yml.

Problem 2: Health check failure blocking dependent services

# 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

Problem 3: node_modules permission issues

Ask Claude Code:

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?"

Container Resource Optimization

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

Pass docker stats output to Claude Code and ask it to "calculate optimal memory limit values" to streamline your production resource planning.

GitHub Actions × Docker — Fully Automated CI/CD Pipelines

Claude Code-Generated CI/CD Workflow

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"

Generated .github/workflows/deploy.yml:

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

With GHA caching, build times drop from ~5 minutes on first run to under 1 minute on subsequent runs.

Security Hardening — Protecting Your Production Containers

Strengthening Security with Claude Code

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."

Key security hardening techniques:

1. Enforce Non-Root Users

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

2. Eliminate Unnecessary Tools

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

3. Read-Only Filesystem

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

4. Safe Secret Management at Build Time

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

Automating Vulnerability Scans

# 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."

Kubernetes Production Deployment — Practical Manifest Design with Claude Code

Generating K8s Manifests

Kubernetes manifest creation is one of Claude Code's strongest suits:

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"

Generated deployment.yaml:

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

Alternative: Fly.io Deployment (Simple Production Without Kubernetes)

When Kubernetes feels like overkill, Fly.io lets you deploy Docker containers to production with a single command:

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

Deployment is as simple as running fly deploy.

Common Errors and How to Fix Them

Error 1: `ENOSPC: no space left on device`

# 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."

Error 2: Build Cache Not Working

# 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."

Error 3: OOM (Out of Memory) in Production Containers

# 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?"

Summary

The Claude Code × Docker combination dramatically accelerates modern container development workflows. Here's a recap of the key points covered in this article:

DevContainer: Reproducible development environments for your entire team. Claude Code auto-generates configuration files.
Multi-stage builds: Production images under 100MB. Claude Code proposes the right Dockerfile architecture for your project.
Docker Compose: Declarative local multi-service environments. Claude Code handles error debugging too.
GitHub Actions CI/CD: Fully automated build, test, security scan, and deploy pipelines.
Security: CIS benchmark compliance via non-root users, read-only filesystems, and proper secret management.
Kubernetes / Fly.io: Scalable production deployments using Claude Code-generated manifests.

With Claude Code, infrastructure design and implementation work that used to take days now takes hours. Decisions like "which base image to use," "how to structure multi-stage builds," and "what resource limits to set in K8s" can all be delegated to Claude Code — freeing you to focus on application logic.

To take your CI/CD further, check out the Claude Code HTTP Hooks × GitHub Actions Integration Guide for advanced automation patterns combining Claude Code hooks with GitHub Actions. If you're running a Next.js application inside a Docker container, the Claude Code × Next.js 15 App Router Production Master Guide covers the application-side design in depth.

Start with DevContainer configuration, have a conversation with Claude Code, and take the path to production one step at a time.

Thank You for Reading

Claude Lab is ad-free, supported entirely by members like you. We publish practical guides daily with implementation code, benchmarks, and production-ready patterns. If you've found it useful, we'd love to have you on board.