Claude Code Docker Compose गाइड: लोकल App, Postgres, Redis और Worker

Docker Compose लोकल विकास के लिए एक साफ नक्शा देता है: web app, PostgreSQL, Redis और background worker को एक साथ चलाना। Docker की Compose documentation इसे multi-container applications को define और run करने का तरीका बताती है, जहां services, networks और volumes एक YAML file में रहते हैं।

Claude Code के साथ यह इसलिए अच्छा काम करता है क्योंकि Compose configuration files में लिखा होता है। “Docker setup बना दो” कहने के बजाय compose.yaml, Dockerfile, .env.example और Makefile देकर Claude Code से review कराएं। इससे output ज्यादा reproducible और team-friendly होता है।

Masa ने इस pattern को एक छोटे Next.js project और queue worker के साथ test किया। सबसे ज्यादा फर्क fancy prompt से नहीं आया, बल्कि इन basic बातों से आया: Postgres ready होने तक wait करना, Redis data persist करना, node_modules को volume में रखना, और migration/test commands को CI जैसा बनाना।

यह article app + PostgreSQL + Redis + worker का copy-paste setup देता है। Compose local development, integration testing और onboarding के लिए बेहतरीन है। Production अलग निर्णय है: orchestration, secrets, monitoring, backups, security boundaries और cost review अलग से चाहिए।

Architecture

flowchart LR
  Dev["Developer"] --> App["app: web server"]
  App --> Pg["postgres: database"]
  App --> Redis["redis: cache and queue"]
  Worker["worker: background jobs"] --> Pg
  Worker --> Redis
  App --> Volume["named volume: node_modules"]
  Pg --> PgVol["named volume: postgres_data"]
  Redis --> RedisVol["named volume: redis_data"]

app web application चलाता है। worker email, webhook, image processing या queue jobs जैसे background काम करता है। postgres और redis में healthcheck है ताकि dependent services सिर्फ container start होने पर नहीं, बल्कि service ready होने पर आगे बढ़ें।

Official syntax के लिए Compose file reference और services reference देखें। Claude Code को review देते समय इन links को आधार बनाने को कहें, ताकि पुराने docker-compose examples से बचा जा सके।

Compose कहां उपयोगी है

Use case	Compose क्यों अच्छा है	सावधानी
Local development	app, DB, Redis और worker एक command से चल जाते हैं	OS के हिसाब से file mount performance बदल सकती है
Integration tests	Test DB और Redis demand पर बनाए जा सकते हैं	CI में ports और cache स्पष्ट रखें
New teammate onboarding	.env.example और make setup setup path fix करते हैं	Example file में real secrets न रखें
Production	छोटे internal tools में candidate हो सकता है	Security, recovery, scaling, monitoring और cost review जरूरी

Production boundary बहुत जरूरी है। Compose developer machines पर समान workbench बनाने में मजबूत है। Production के लिए ECS, Kubernetes, Cloud Run, Fly.io, Render या अपनी existing platform से तुलना करें। Claude Code से migration constraints लिखवाएं, local file को सीधे deployment plan न मानें।

Copy-paste compose.yaml

यह example Node.js या Next.js project मानकर लिखा गया है। npm run dev, npm run worker:dev और migration scripts को अपने package.json के हिसाब से बदलें।

# compose.yaml
services:
  app:
    build:
      context: .
      dockerfile: Dockerfile
      target: dev
    command: npm run dev -- --hostname 0.0.0.0
    ports:
      - "3000:3000"
    env_file:
      - .env
    environment:
      DATABASE_URL: postgresql://${POSTGRES_USER}:${POSTGRES_PASSWORD}@postgres:5432/${POSTGRES_DB}?schema=public
      REDIS_URL: redis://redis:6379
    volumes:
      - .:/workspace
      - node_modules:/workspace/node_modules
    depends_on:
      postgres:
        condition: service_healthy
      redis:
        condition: service_healthy
    healthcheck:
      test: ["CMD-SHELL", "node -e \"fetch('http://127.0.0.1:3000/api/health').then(r=>process.exit(r.ok?0:1)).catch(()=>process.exit(1))\""]
      interval: 10s
      timeout: 5s
      retries: 12
      start_period: 20s

  worker:
    build:
      context: .
      dockerfile: Dockerfile
      target: dev
    command: npm run worker:dev
    env_file:
      - .env
    environment:
      DATABASE_URL: postgresql://${POSTGRES_USER}:${POSTGRES_PASSWORD}@postgres:5432/${POSTGRES_DB}?schema=public
      REDIS_URL: redis://redis:6379
    volumes:
      - .:/workspace
      - node_modules:/workspace/node_modules
    depends_on:
      postgres:
        condition: service_healthy
      redis:
        condition: service_healthy

  postgres:
    image: postgres:16-alpine
    ports:
      - "5432:5432"
    env_file:
      - .env
    environment:
      POSTGRES_USER: ${POSTGRES_USER}
      POSTGRES_PASSWORD: ${POSTGRES_PASSWORD}
      POSTGRES_DB: ${POSTGRES_DB}
    volumes:
      - postgres_data:/var/lib/postgresql/data
      - ./docker/postgres/init:/docker-entrypoint-initdb.d:ro
    healthcheck:
      test: ["CMD-SHELL", "pg_isready -U $$POSTGRES_USER -d $$POSTGRES_DB"]
      interval: 5s
      timeout: 5s
      retries: 10

  redis:
    image: redis:7-alpine
    command: ["redis-server", "--appendonly", "yes"]
    ports:
      - "6379:6379"
    volumes:
      - redis_data:/data
    healthcheck:
      test: ["CMD", "redis-cli", "ping"]
      interval: 5s
      timeout: 3s
      retries: 10

volumes:
  node_modules:
  postgres_data:
  redis_data:

तीन बातें याद रखें। Containers एक-दूसरे को service name से access करते हैं, इसलिए postgres:5432 और redis:6379 लिखें, localhost नहीं। node_modules को named volume में रखने से source bind mount container dependencies को overwrite नहीं करता। Postgres healthcheck में double dollar sign इसलिए है ताकि variable container shell में expand हो।

Dockerfile

एक Dockerfile में dev, build और production stages रखना beginners के लिए अलग-अलग Dockerfile संभालने से आसान होता है।

# Dockerfile
# syntax=docker/dockerfile:1

FROM node:22-alpine AS base
WORKDIR /workspace
ENV NEXT_TELEMETRY_DISABLED=1
COPY package*.json ./
RUN npm ci

FROM base AS dev
EXPOSE 3000
CMD ["npm", "run", "dev", "--", "--hostname", "0.0.0.0"]

FROM base AS build
COPY . .
RUN npm run build

FROM node:22-alpine AS production
WORKDIR /workspace
ENV NODE_ENV=production
ENV NEXT_TELEMETRY_DISABLED=1
COPY package*.json ./
RUN npm ci --omit=dev
COPY --from=build /workspace/.next ./.next
COPY --from=build /workspace/public ./public
USER node
EXPOSE 3000
CMD ["npm", "start"]

dev stage source code copy नहीं करता क्योंकि Compose उसे volume से mount करेगा। build stage पूरा repository copy करता है ताकि CI और production image local machine पर depend न करें।

.env.example

.env commit न करें। .env.example commit करें, जिसमें variable names और safe sample values हों।

# .env.example
POSTGRES_USER=app
POSTGRES_PASSWORD=app_password
POSTGRES_DB=app_development

DATABASE_URL=postgresql://app:app_password@postgres:5432/app_development?schema=public
REDIS_URL=redis://redis:6379
NODE_ENV=development
PORT=3000

env_file variables को containers में भेजता है। Compose file interpolation project के .env को भी पढ़ता है। दोनों concepts मिलते-जुलते हैं, लेकिन एक जैसे नहीं; values aligned रखें।

Makefile और one-off commands

Common commands को Makefile में रखें। अगर team make नहीं इस्तेमाल करती, तो इन्हीं commands को package.json scripts में रख सकते हैं।

COMPOSE = docker compose --env-file .env -f compose.yaml

.PHONY: setup up up-d down restart logs ps app-shell db-shell redis-cli migrate seed test lint clean

setup:
	cp .env.example .env
	$(COMPOSE) build

up:
	$(COMPOSE) up --build

up-d:
	$(COMPOSE) up -d --build

down:
	$(COMPOSE) down

restart:
	$(COMPOSE) restart app worker

logs:
	$(COMPOSE) logs -f app worker postgres redis

ps:
	$(COMPOSE) ps

app-shell:
	$(COMPOSE) exec app sh

db-shell:
	$(COMPOSE) exec postgres psql -U app -d app_development

redis-cli:
	$(COMPOSE) exec redis redis-cli

migrate:
	$(COMPOSE) run --rm app npm run db:migrate

seed:
	$(COMPOSE) run --rm app npm run db:seed

test:
	$(COMPOSE) run --rm app npm test

lint:
	$(COMPOSE) run --rm app npm run lint

clean:
	$(COMPOSE) down --volumes --remove-orphans

exec already running container में command चलाता है। run --rm नया temporary container बनाकर lint, test, migration या seed जैसी one-off task चलाता है। इससे local और CI behavior करीब आते हैं।

Claude Code review prompt

Claude Code common workflows रोजमर्रा के काम को छोटे tasks में बांटने की सलाह देता है: समझना, edit करना, test करना और review करना। Compose review में भी यही तरीका रखें।

इस repository की Docker Compose setup review करें।

Files:
- compose.yaml
- Dockerfile
- .env.example
- package.json
- CI workflow files अगर मौजूद हों

Check:
1. app + postgres + redis + worker local में चल सकते हैं
2. healthcheck और depends_on सही तरह से use हुए हैं
3. named volumes और bind mounts सुरक्षित हैं
4. .env.example में real secrets नहीं हैं
5. migrate, seed, test और lint के one-off commands हैं
6. CI risks: ports, cache, permissions, startup wait
7. production में ले जाने से पहले कौन-कौन से reviews जरूरी हैं

Constraints:
- existing framework और package manager follow करें
- बड़े refactor को proposal तक रखें
- edit करें तो reason और verification command लिखें

इस prompt को CLAUDE.md के पास रखें ताकि team वही review standard दोहरा सके। Related guides: Dev Container guide और CI/CD setup guide।

Practical use cases

पहला use case है new teammate का first-day setup। .env.example copy करके make up चलाने से app, DB, Redis और worker तैयार हो जाते हैं। README छोटा होता है और support questions ज्यादा precise बनते हैं।

दूसरा use case है queue processing की local testing। Email, image processing, billing webhook और notifications अक्सर worker में चलते हैं। Compose में worker जोड़ने से Redis queue jobs local में reproduce होते हैं।

तीसरा use case है integration tests को stable बनाना। कई bugs SQLite shortcut में pass हो जाते हैं लेकिन Postgres में fail होते हैं। Compose managed Postgres और Redis से SQL dialect, migration और queue behavior जल्दी दिखते हैं।

चौथा use case है Claude Code से infrastructure review। इंसान अक्सर localhost, stale volume, missing healthcheck या example secrets miss कर देता है। Reusable prompt इसे checklist में बदल देता है।

Common pitfalls

सबसे आम गलती app container से DB को localhost पर connect करना है। Compose network में service names DNS names होते हैं। postgres और redis use करें।

दूसरी गलती depends_on को complete readiness guarantee मानना है। condition: service_healthy मदद करता है, लेकिन app में retry logic और worker में migration order की safety फिर भी चाहिए।

Stale named volumes भी confusion बनाते हैं। Schema बदल गया लेकिन postgres_data बचा रहा तो local state repository से अलग हो सकती है। Fresh test के लिए make clean चलाएं, लेकिन याद रखें कि local data delete होगा।

.env.example में real API keys न रखें। Sample values जैसे app_password या replace_me use करें। Production secrets Docker secrets, cloud secret manager या CI secret store में रखें।

अंत में, local Compose file को production plan न मानें। Production में TLS, network exposure, DB backups, Redis persistence, monitoring, vulnerability scan, image provenance, permissions और cost review जरूरी हैं।

ClaudeCodeLab training और templates

अगर इस setup को अपने repository के हिसाब से customize करना है, तो ClaudeCodeLab के products and templates से CLAUDE.md, review prompts और setup runbooks standardize करें। Team rollout, Docker Desktop differences, CI/CD, permissions या production boundary तय करनी हो तो training and consultation देखें।

Official references: Docker Compose, Compose file reference, services reference और Claude Code common workflows।

इस article की setup को वास्तव में test करने पर Masa के sample project में make up से app, Postgres, Redis और worker साथ में start हुए। Healthchecks ने वह race कम की जिसमें app database ready होने से पहले fail हो जाता था। बची हुई sharp edge stale named volume थी: पुराने data से migration गलत वजह से broken या fixed लग सकती है। Practical conclusion यही है कि Compose local development के लिए मजबूत base है, लेकिन production के लिए security, operations, recovery और cost की अलग review जरूरी है।