Panduan Praktis Claude Code Docker Compose: App Lokal, Postgres, Redis, dan Worker

Docker Compose adalah cetak biru untuk menjalankan app, PostgreSQL, Redis, dan background worker di lingkungan lokal. Dokumentasi Docker Compose menjelaskan Compose sebagai alat untuk mendefinisikan dan menjalankan aplikasi multi-container, dengan services, networks, dan volumes dalam satu file YAML.

Ini cocok dengan Claude Code karena konfigurasi Compose bisa dibaca sebagai file. Daripada meminta “buatkan setup Docker” secara umum, berikan compose.yaml, Dockerfile, .env.example, dan Makefile agar Claude Code bisa melakukan review yang konkret. Hasilnya lebih mudah diulang dan lebih aman untuk tim.

Saat Masa mencoba pola ini pada project kecil Next.js dengan queue worker, yang paling membantu bukan prompt yang rumit. Yang membantu adalah keputusan sederhana: menunggu Postgres siap, membuat Redis persistent, menjaga node_modules dengan volume, dan menyamakan command migration/test dengan CI.

Artikel ini memberi contoh app + PostgreSQL + Redis + worker yang bisa disalin. Compose sangat bagus untuk local development, integration test, dan onboarding. Production adalah keputusan berbeda: orchestration, secrets, monitoring, backup, security boundary, dan cost harus direview terpisah.

Arsitektur

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 menjalankan web application. worker memproses email, webhook, image processing, atau job queue. postgres dan redis memakai healthcheck supaya service lain menunggu kesiapan nyata, bukan hanya container yang sudah start.

Untuk sintaks resmi, gunakan Compose file reference dan services reference. Saat meminta Claude Code mereview, sebutkan dua referensi ini agar tidak memakai contoh lama dari era docker-compose.

Kapan Compose Tepat Digunakan

Kebutuhan	Mengapa Compose cocok	Perhatian
Local development	Satu command menjalankan app, DB, Redis, dan worker	Performa file mount berbeda antar OS
Integration test	Test DB dan Redis bisa dibuat sesuai kebutuhan	Port dan cache di CI harus eksplisit
Onboarding anggota baru	.env.example dan make setup membuat langkah tetap	Jangan taruh secret asli di contoh
Production	Kadang cocok untuk internal tool kecil	Tetap butuh review security, recovery, scale, monitoring, dan cost

Batas production penting. Compose kuat untuk membuat workbench yang sama di setiap laptop developer. Untuk production, bandingkan dengan ECS, Kubernetes, Cloud Run, Fly.io, Render, atau platform yang sudah dipakai. Mintalah Claude Code membuat daftar constraint migrasi, bukan langsung menjadikan file lokal sebagai deployment plan.

compose.yaml yang Bisa Disalin

Contoh ini mengasumsikan Node.js atau Next.js. Ganti npm run dev, npm run worker:dev, dan script migration sesuai package.json Anda.

# 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:

Ada tiga detail yang perlu dijaga. Container saling mengakses lewat service name, jadi gunakan postgres:5432 dan redis:6379, bukan localhost. node_modules memakai named volume agar bind mount source code tidak menimpa dependency di container. Double dollar sign pada healthcheck Postgres membuat variable dibaca oleh shell di dalam container.

Dockerfile

Satu Dockerfile dengan stage dev, build, dan production biasanya lebih mudah dijaga daripada beberapa Dockerfile terpisah.

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

Stage dev tidak menyalin source code karena Compose akan mount dari host. Stage build menyalin seluruh repository agar CI dan production image tidak bergantung pada kondisi laptop developer.

.env.example

Commit .env.example, jangan commit .env. File contoh harus menunjukkan bentuk konfigurasi tanpa credential asli.

# .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 mengirim variable ke container. Interpolation di file Compose juga membaca .env project. Bedakan dua hal ini dan jaga nilainya konsisten.

Makefile dan One-Off Command

Command yang sering dipakai sebaiknya ditaruh di Makefile. Jika tim tidak memakai make, pindahkan command yang sama ke scripts di package.json.

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

Gunakan exec untuk container yang sudah berjalan. Gunakan run --rm untuk tugas sekali jalan seperti lint, test, migration, atau seed. Ini membuat local workflow lebih mirip CI.

Prompt Review untuk Claude Code

Claude Code common workflows menyarankan pekerjaan harian dipecah menjadi tugas kecil: memahami, mengedit, menguji, dan mereview. Terapkan prinsip yang sama untuk Compose.

Review setup Docker Compose di repository ini.

Files:
- compose.yaml
- Dockerfile
- .env.example
- package.json
- CI workflow files jika ada

Periksa:
1. app + postgres + redis + worker bisa berjalan lokal
2. healthcheck dan depends_on dipakai dengan benar
3. named volume dan bind mount aman
4. .env.example tidak berisi secret asli
5. command one-off untuk migrate, seed, test, dan lint tersedia
6. risiko CI: port, cache, permission, dan startup wait
7. hal yang wajib direview sebelum pola ini dipakai di production

Constraint:
- ikuti framework dan package manager yang sudah ada
- refactor besar cukup sebagai proposal
- jika mengedit, jelaskan alasan dan command verifikasi

Simpan prompt ini dekat CLAUDE.md agar standar review bisa diulang. Baca juga Dev Container guide dan CI/CD setup guide.

Use Case Praktis

Use case pertama adalah onboarding hari pertama. Jika anggota baru cukup copy .env.example dan menjalankan make up, app, DB, Redis, dan worker langsung tersedia tanpa install layanan satu per satu.

Use case kedua adalah testing queue lokal. Email, image processing, billing webhook, dan notification fan-out biasanya berada di worker. Dengan worker di Compose, job Redis queue bisa direproduksi di laptop.

Use case ketiga adalah integration test yang lebih stabil. Banyak bug lolos di SQLite shortcut tetapi gagal di Postgres. Compose membuat test lebih dekat ke DB dan Redis nyata, sehingga perbedaan SQL, migration, dan queue behavior terlihat lebih awal.

Use case keempat adalah infrastructure review dengan Claude Code. Manusia mudah melewatkan localhost, volume lama, healthcheck yang hilang, atau secret di contoh env. Prompt yang bisa dipakai ulang mengubah review menjadi checklist.

Jebakan Umum

Kesalahan paling umum adalah app container mencoba konek ke DB lewat localhost. Di jaringan Compose, service name adalah hostname. Gunakan postgres dan redis.

Kesalahan berikutnya adalah menganggap depends_on sebagai jaminan readiness penuh. condition: service_healthy membantu, tetapi app tetap butuh retry, dan worker tidak boleh menjalankan tugas kritis sebelum migration selesai.

Named volume lama juga sering membuat diagnosis salah. Jika schema berubah tetapi postgres_data masih ada, state lokal bisa tidak sesuai repository. Gunakan make clean untuk mulai bersih, dengan sadar bahwa data lokal akan dihapus.

Jangan taruh API key asli di .env.example. Gunakan nilai seperti app_password atau replace_me. Secret production sebaiknya ada di Docker secrets, cloud secret manager, atau CI secret store.

Terakhir, jangan jadikan Compose lokal sebagai production plan tanpa review. Production memerlukan TLS, network exposure, DB backup, Redis persistence, monitoring, vulnerability scan, image provenance, permission, dan cost control.

Training dan Template ClaudeCodeLab

Untuk menyesuaikan setup ini ke repository Anda, mulai dari products and templates ClaudeCodeLab agar CLAUDE.md, prompt review, dan setup runbook menjadi standar. Jika masalahnya adalah rollout tim, perbedaan Docker Desktop, CI/CD, permission, atau batas antara Compose dan orchestration production, gunakan halaman training and consultation.

Referensi resmi: Docker Compose, Compose file reference, services reference, dan Claude Code common workflows.

Setelah isi artikel ini benar-benar dicoba, project uji Masa bisa menjalankan app, Postgres, Redis, dan worker dengan make up, dan healthcheck mengurangi race ketika app start sebelum database siap. Sisi tajam yang masih terasa adalah named volume lama: data lama bisa membuat migration terlihat rusak atau terlihat berhasil karena alasan yang salah. Kesimpulannya, Compose adalah fondasi kuat untuk local development, tetapi production tetap perlu review terpisah untuk security, operasi, recovery, dan cost.