Claude Code और Docker: Compose, Volume, Network और CI Build

पहले तय करें कि Claude Code क्या करेगा

अगर आप Claude Code से सिर्फ “इस app को Dockerize कर दो” कहेंगे, तो वह ऐसा Dockerfile दे सकता है जो एक बार चल जाए लेकिन review करना मुश्किल हो। Docker application runtime को package करता है। Image template है, container running instance है, volume container के बाहर data बचाता है, और network services को नाम से connect करने देता है।

Real project में Dockerfile अकेला काम नहीं है। Dockerfile, docker-compose.yml, .dockerignore, environment variables, health checks और CI build को साथ में review करना चाहिए। काम करते समय official docs खोलकर रखें: Dockerfile reference, Compose file reference, Docker build best practices, Docker Build GitHub Actions और Claude Code overview।

CI side के लिए Claude Code CI/CD setup पढ़ें। Permission और sandbox boundary के लिए approval and sandbox guide और security best practices उपयोगी हैं।

Practical use cases

Docker integration का मतलब fancy setup नहीं है। इसका मतलब है कि team environment को guess न करे। पहले problem लिखें, फिर Claude Code को edit करने दें।

Use case	Docker क्या fix करता है	Claude Code से क्या मांगें
New developer onboarding	Node.js, PostgreSQL, Redis, ports, startup commands	docker compose up से stack चलाना
Production-like debugging	Env vars, service names, health checks, startup order	local और production differences list करना
PR verification	Dockerfile, lockfile, build cache, CI logs	image build करने वाला workflow जोड़ना
Training और handoff	Commands, failure modes, recovery steps	CLAUDE.md और README rules लिखना

Monetized SaaS या content site में यह revenue से जुड़ता है। Checkout, lead form, admin screen और product page किसी एक laptop पर निर्भर नहीं होने चाहिए। Solo builders ClaudeCodeLab products से शुरू कर सकते हैं। Teams जिन्हें real repository में permission, CI और review policy चाहिए, वे Claude Code training and consultation देखें।

Claude Code को guardrails के साथ prompt दें

पहले prompt में context, expected files, forbidden actions और verification commands रखें। इससे unsafe लेकिन believable Docker setup से बचते हैं।

Dockerize this Node.js + TypeScript API.

Context:
- pnpm is the package manager.
- The app listens on port 3000.
- GET /health returns 200.
- Local development needs PostgreSQL 16 and Redis 7.

Create:
- Production multi-stage Dockerfile
- docker-compose.yml for local development
- .dockerignore
- Docker-related package.json scripts
- GitHub Actions workflow that only verifies docker build

Constraints:
- Do not run the production container as root.
- Do not COPY .env files or secrets into the image.
- Explain the volume and network choices for the README.
- Include verification commands and how to inspect failures.

Multi-stage build में build environment और runtime environment अलग होते हैं। TypeScript compile tools build stage में रहते हैं, और final image में सिर्फ production dependencies और dist जाता है। इससे image छोटी और safer होती है।

Copy-paste Dockerfile

यह example Node.js API मानता है जो src/index.ts को dist/index.js में build करता है। dev stage local Compose के लिए है और runner production image है।

# syntax=docker/dockerfile:1

FROM node:22-bookworm-slim AS base
ENV PNPM_HOME="/pnpm"
ENV PATH="$PNPM_HOME:$PATH"
WORKDIR /app
RUN corepack enable

FROM base AS dev
ENV NODE_ENV=development
COPY package.json pnpm-lock.yaml ./
RUN pnpm install --frozen-lockfile
COPY . .
CMD ["pnpm", "dev"]

FROM base AS deps
COPY package.json pnpm-lock.yaml ./
RUN pnpm install --frozen-lockfile

FROM deps AS build
COPY tsconfig.json ./
COPY src ./src
RUN pnpm build

FROM base AS prod-deps
ENV NODE_ENV=production
COPY package.json pnpm-lock.yaml ./
RUN pnpm install --frozen-lockfile --prod && pnpm store prune

FROM base AS runner
ENV NODE_ENV=production
RUN groupadd --system --gid 1001 nodejs \
  && useradd --system --uid 1001 --gid nodejs appuser
COPY --from=prod-deps --chown=appuser:nodejs /app/node_modules ./node_modules
COPY --from=build --chown=appuser:nodejs /app/dist ./dist
COPY --chown=appuser:nodejs package.json ./
USER appuser
EXPOSE 3000
HEALTHCHECK --interval=30s --timeout=3s --retries=3 CMD node -e "fetch('http://127.0.0.1:3000/health').then(r=>process.exit(r.ok?0:1)).catch(()=>process.exit(1))"
CMD ["node", "dist/index.js"]

Review के लिए Claude Code से पूछें: क्या secrets image में जा सकते हैं, क्या COPY order cache friendly है, और क्या runtime image में devDependencies नहीं हैं।

Compose में Volume और Network समझें

Compose कई containers को साथ में start करता है। इस stack में API, PostgreSQL और Redis एक network पर हैं, इसलिए API postgres और redis service names से connect करती है। Volume data को disposable container से बाहर रखता है। pgdata database files बचाता है, और api_node_modules host के node_modules को Linux container dependencies पर चढ़ने से रोकता है।

services:
  api:
    build:
      context: .
      target: dev
    command: pnpm dev
    ports:
      - "3000:3000"
    environment:
      NODE_ENV: development
      DATABASE_URL: postgres://app:app@postgres:5432/app
      REDIS_URL: redis://redis:6379
    depends_on:
      postgres:
        condition: service_healthy
      redis:
        condition: service_healthy
    volumes:
      - .:/app
      - api_node_modules:/app/node_modules
    healthcheck:
      test: ["CMD", "node", "-e", "fetch('http://127.0.0.1:3000/health').then(r=>process.exit(r.ok?0:1)).catch(()=>process.exit(1))"]
      interval: 10s
      timeout: 3s
      retries: 5

  postgres:
    image: postgres:16-alpine
    environment:
      POSTGRES_USER: app
      POSTGRES_PASSWORD: app
      POSTGRES_DB: app
    ports:
      - "5432:5432"
    volumes:
      - pgdata:/var/lib/postgresql/data
    healthcheck:
      test: ["CMD-SHELL", "pg_isready -U app -d app"]
      interval: 5s
      timeout: 3s
      retries: 10

  redis:
    image: redis:7-alpine
    ports:
      - "6379:6379"
    healthcheck:
      test: ["CMD", "redis-cli", "ping"]
      interval: 5s
      timeout: 3s
      retries: 10

volumes:
  pgdata:
  api_node_modules:

depends_on startup order संभालता है, लेकिन database ready है यह अपने आप prove नहीं करता। इसलिए healthcheck और condition: service_healthy साथ रखें।

Secrets को build context से बाहर रखें

सबसे पहले .dockerignore लिखें। यह build context छोटा करता है और .env copy होने से रोकता है।

.git
node_modules
dist
coverage
.env
.env.*
!.env.example
npm-debug.log*
pnpm-debug.log*
Dockerfile*
docker-compose*.yml

फिर shared commands को package.json में रखें ताकि team और Claude Code एक ही command names use करें।

{
  "scripts": {
    "dev": "tsx watch src/index.ts",
    "build": "tsc -p tsconfig.json",
    "start": "node dist/index.js",
    "docker:dev": "docker compose up --build",
    "docker:check": "bash scripts/docker-check.sh"
  },
  "dependencies": {
    "@fastify/redis": "latest",
    "fastify": "latest",
    "pg": "latest"
  },
  "devDependencies": {
    "tsx": "latest",
    "typescript": "latest"
  }
}

Repeatable verification script

Manual check अक्सर skip हो जाता है। scripts/docker-check.sh में steps रखें।

#!/usr/bin/env bash
set -euo pipefail

docker compose build api
docker compose up -d postgres redis api

cleanup() {
  docker compose down
}
trap cleanup EXIT

for attempt in {1..30}; do
  if curl -fsS http://127.0.0.1:3000/health >/dev/null; then
    echo "healthcheck ok"
    exit 0
  fi
  echo "waiting for api... ${attempt}/30"
  sleep 2
done

docker compose logs api
exit 1

यह script image build करता है, stack start करता है, /health wait करता है और fail होने पर API logs दिखाता है।

CI में पहले build, बाद में push

पहले PR में registry push मत करें। सिर्फ image build verify करें। Push, signing, vulnerability scan और SBOM बाद में जोड़ें।

name: docker-build

on:
  pull_request:
  push:
    branches:
      - main

jobs:
  image:
    runs-on: ubuntu-latest
    permissions:
      contents: read
      packages: write
    steps:
      - uses: actions/checkout@v4
      - uses: docker/setup-buildx-action@v3
      - uses: docker/build-push-action@v7
        with:
          context: .
          target: runner
          push: false
          tags: claude-code-docker-sample:${{ github.sha }}
          cache-from: type=gha
          cache-to: type=gha,mode=max

Claude Code से explain करवाएं कि workflow push करता है या नहीं, permissions जरूरत से ज्यादा हैं या नहीं, और cache खाली हो तो build चलेगा या नहीं।

Common failures

सबसे महंगी गलती .env को image में copy करना है। Secret registry में चला गया तो cleanup slow होता है। .dockerignore, CI secrets और build logs साथ में check करें।

दूसरी गलती host node_modules को Linux container में mount करना है। macOS, Windows और Linux native packages अलग हो सकते हैं। Named volume इससे बचाता है।

तीसरी गलती startup race है: API database ready होने से पहले start होकर fail हो जाती है। DB health check और application retry दोनों रखें।

चौथी गलती production container को root से चलाना है। Demo में चलता है, पर risk बढ़ता है। Claude Code से exact Dockerfile lines दिखाने को कहें जो non-root prove करती हैं।

Safe workflow

Recommended order है: repository inspect, runtime dependencies list, .dockerignore, local Compose, production Dockerfile, verification script, फिर CI। हर step के बाद human git diff पढ़े और Claude Code से चार चीजें लिखवाए: changed files, reason, verification command, remaining risk।

यह session handoff template के साथ अच्छा काम करता है। Docker integration एक बार generate किया गया file नहीं, बल्कि team habit होना चाहिए।

Practical result

Practical use में Claude Code को छोटे tasks देना बेहतर रहा। .dockerignore, फिर Compose, फिर health checks, फिर CI से diffs review करना आसान हुआ। Named api_node_modules volume और database service_healthy wait ने दो beginner problems कम कीं: “मेरे laptop पर ही चलता है” और “API start हुई लेकिन Postgres से connect नहीं हुई”।