Claude Code Devcontainer गाइड: दोहराया जा सकने वाला dev environment

Claude Code तब सबसे अच्छा काम करता है जब development environment साफ और repeatable हो। अगर एक developer Node.js 22 चला रहा है, दूसरा Node.js 20 पर है, PostgreSQL हर laptop पर अलग तरह से install है और Redis कहीं है, कहीं नहीं, तो AI agent code से पहले environment की समस्या में उलझ जाता है।

Dev Container इस समस्या को repository की configuration में बदल देता है। Editor Docker container से जुड़ता है और terminal, language server, tests, database tools और Claude Code उसी container के अंदर चलते हैं। इस guide में हम Next.js + TypeScript project के लिए practical .devcontainer/devcontainer.json, Dockerfile, docker-compose.yml, postCreateCommand, permissions, secrets, volumes और port-forward setup बनाएंगे।

2 जून 2026 तक Claude Code की official docs में Development containers page है, जिसमें Dev Container Feature, credentials persistence, network limits और permission prompt skip करने के risk बताए गए हैं। Dev Container के लिए VS Code Dev Containers docs और Dev Container Specification भी देखें।

Claude Code के लिए devcontainer क्यों उपयोगी है

Claude Code files पढ़ता है, code edit करता है, commands चलाता है और test failures से अगला fix समझता है। इसलिए environment अस्पष्ट नहीं होना चाहिए। Host machine पर चलाने से पुराने global packages, personal cloud credentials, दूसरे project की environment variables या अलग database गलती से visible हो सकते हैं।

devcontainer में काम करने पर working surface repository में defined होती है। Node.js version, OS packages, Claude Code CLI version, VS Code extensions, lifecycle commands, volumes और forwarded ports reviewable बन जाते हैं। जब Claude Code कहता है कि उसने npm test चलाया, team जानती है कि command किस environment में चला।

flowchart LR
  Host["Host machine"] --> Editor["VS Code / Cursor"]
  Editor --> Container["Dev Container"]
  Container --> Claude["Claude Code CLI"]
  Container --> Tools["Node.js / npm / psql / redis-cli"]
  Container --> Services["PostgreSQL / Redis"]
  Container --> Repo["Mounted repository"]
  Claude --> Repo
  Claude --> Tools

तीन use cases बहुत मजबूत हैं। पहला onboarding: नए member को सिर्फ Docker और editor extension चाहिए। दूसरा remote development: वही .devcontainer local और Codespaces दोनों में चलता है। तीसरा AI debugging: lint, typecheck और tests किसी एक laptop पर निर्भर नहीं रहते।

कौन से files बनेंगे

इस setup में app, services और Claude Code state अलग रहेंगे।

File	काम	Review point
.devcontainer/devcontainer.json	Editor के लिए entry config	remoteUser, ports, mounts, lifecycle commands
.devcontainer/Dockerfile	Tools और Claude Code install करता है	CLI version, non-root user, OS packages
.devcontainer/docker-compose.yml	app, PostgreSQL, Redis चलाता है	volumes, healthcheck, exposed ports
.devcontainer/post-create.sh	पहली बार setup करता है	lockfile, Prisma, error handling
.claude/settings.json	Claude Code permissions	.env, secrets, push, dangerous Docker commands

devcontainer.json

.devcontainer/devcontainer.json बनाएं। यह valid JSON है, इसलिए comments न डालें।

{
  "name": "claude-code-next-dev",
  "dockerComposeFile": "docker-compose.yml",
  "service": "app",
  "workspaceFolder": "/workspaces/app",
  "remoteUser": "node",
  "shutdownAction": "stopCompose",
  "waitFor": "postCreateCommand",
  "postCreateCommand": "bash .devcontainer/post-create.sh",
  "postStartCommand": "git config --global --add safe.directory /workspaces/app || true",
  "forwardPorts": [3000, 5432, 6379],
  "portsAttributes": {
    "3000": { "label": "Next.js", "onAutoForward": "notify" },
    "5432": { "label": "PostgreSQL", "onAutoForward": "silent" },
    "6379": { "label": "Redis", "onAutoForward": "silent" }
  },
  "mounts": [
    "source=claude-code-config-${devcontainerId},target=/home/node/.claude,type=volume"
  ],
  "containerEnv": {
    "NODE_ENV": "development",
    "DISABLE_AUTOUPDATER": "1",
    "CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC": "1"
  },
  "customizations": {
    "vscode": {
      "extensions": [
        "anthropic.claude-code",
        "dbaeumer.vscode-eslint",
        "esbenp.prettier-vscode",
        "ms-azuretools.vscode-docker"
      ],
      "settings": {
        "editor.formatOnSave": true,
        "editor.defaultFormatter": "esbenp.prettier-vscode",
        "typescript.tsdk": "node_modules/typescript/lib",
        "terminal.integrated.defaultProfile.linux": "bash"
      }
    }
  }
}

remoteUser को non-root रखें। Container safe boundary देता है, लेकिन workspace host repository से mount होता है। Claude Code अगर /workspaces/app में file हटाएगा, तो host पर भी file हटेगी। /home/node/.claude के लिए project-specific named volume credentials और settings को rebuild के बाद बचाता है, लेकिन host का पूरा home expose नहीं करता।

Compose, Dockerfile और setup script

.devcontainer/docker-compose.yml app, PostgreSQL और Redis को साथ चलाता है। पहले forwardPorts इस्तेमाल करें; database ports को Compose ports से publish करना तभी जरूरी है जब external tool चाहिए।

services:
  app:
    build:
      context: ..
      dockerfile: .devcontainer/Dockerfile
    command: sleep infinity
    volumes:
      - ..:/workspaces/app:cached
      - node_modules:/workspaces/app/node_modules
      - claude_code_config:/home/node/.claude
    environment:
      DATABASE_URL: postgresql://app:app_password@db:5432/app
      REDIS_URL: redis://redis:6379
      NEXT_TELEMETRY_DISABLED: "1"
    depends_on:
      db:
        condition: service_healthy
      redis:
        condition: service_healthy

  db:
    image: postgres:16-alpine
    restart: unless-stopped
    environment:
      POSTGRES_USER: app
      POSTGRES_PASSWORD: app_password
      POSTGRES_DB: app
    volumes:
      - postgres_data:/var/lib/postgresql/data
    healthcheck:
      test: ["CMD-SHELL", "pg_isready -U app -d app"]
      interval: 5s
      timeout: 5s
      retries: 20

  redis:
    image: redis:7-alpine
    restart: unless-stopped
    volumes:
      - redis_data:/data
    healthcheck:
      test: ["CMD", "redis-cli", "ping"]
      interval: 5s
      timeout: 5s
      retries: 20

volumes:
  node_modules:
  claude_code_config:
  postgres_data:
  redis_data:

Dockerfile में Claude Code CLI version pin करें। 2 जून 2026 को npm view @anthropic-ai/claude-code version ने 2.1.160 दिखाया।

FROM mcr.microsoft.com/devcontainers/typescript-node:1-22-bookworm

ARG CLAUDE_CODE_VERSION=2.1.160

ENV DISABLE_AUTOUPDATER=1
ENV NEXT_TELEMETRY_DISABLED=1

RUN apt-get update \
    && apt-get install -y --no-install-recommends \
      jq \
      postgresql-client \
      redis-tools \
      ripgrep \
    && rm -rf /var/lib/apt/lists/*

RUN npm install -g "@anthropic-ai/claude-code@${CLAUDE_CODE_VERSION}" \
    && npm cache clean --force

USER node
WORKDIR /workspaces/app

RUN mkdir -p /home/node/.claude

.devcontainer/post-create.sh dependency setup संभालता है।

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

cd /workspaces/app
corepack enable

if [ -f pnpm-lock.yaml ]; then
  pnpm install --frozen-lockfile
elif [ -f yarn.lock ]; then
  yarn install --immutable
elif [ -f package-lock.json ]; then
  npm ci
elif [ -f package.json ]; then
  npm install
fi

if [ -f prisma/schema.prisma ]; then
  npx prisma generate
fi

node --version
npm --version
claude --version || true

यह script lockfile का सम्मान करता है। postCreateCommand में npm run dev जैसे long-running server न चलाएं; वह terminal या task से चलना चाहिए।

Permissions, secrets, volumes और ports

Production .env, ~/.ssh, ~/.aws या ~/.config/gcloud को default mount न करें। सबसे safe secret वही है जो container में गया ही नहीं। Development database URL Compose के internal db service पर रख सकते हैं; real API keys को managed secrets या short-lived tokens से दें।

.claude/settings.json में project permissions लिखें।

{
  "$schema": "https://json.schemastore.org/claude-code-settings.json",
  "permissions": {
    "allow": [
      "Bash(npm run lint)",
      "Bash(npm run test *)",
      "Bash(npm run typecheck)",
      "Bash(claude --version)"
    ],
    "deny": [
      "Read(./.env)",
      "Read(./.env.*)",
      "Read(./secrets/**)",
      "Bash(printenv *)",
      "Bash(git push *)",
      "Bash(docker system prune *)"
    ]
  }
}

Volumes speed देते हैं, लेकिन old state भी बचाते हैं। node_modules को container volume में रखना बेहतर है। PostgreSQL volume migration experiments के बाद stale हो सकता है, इसलिए README में लिखें कि docker compose -f .devcontainer/docker-compose.yml down -v कब चलाना सुरक्षित है।

Common failures और verification

Common failures हैं: Claude Code को root से चलाना, CLI version pin न करना, production secrets mount करना, postCreateCommand में long server शुरू करना और 5432/6379 को बिना जरूरत publish करना। Rebuild के बाद node --version, npm --version, claude --version, कम से कम एक lint या test command और http://localhost:3000 check करें।

Service setup के लिए Claude Code Docker Compose guide पढ़ें। Release flow के लिए Claude Code CI/CD setup guide उपयोगी है। अगर आपकी team devcontainer, CLAUDE.md, permissions और review checklist को standard बनाना चाहती है, तो training / consultation से शुरुआत करें।

Try करने के बाद निष्कर्ष

एक छोटे Next.js repo में इस setup को try करने पर सबसे बड़ा फायदा तीन जगह मिला: postCreateCommand अलग script में था, node_modules container volume में था और /home/node/.claude project-specific volume में बचा। Rebuild के बाद Claude Code version, dependency install, Prisma generation और 3000 port check एक ही तरह से repeat हुआ। मुख्य सावधानी database volume थी, क्योंकि repeated migrations old state छोड़ सकती हैं।