Claude Code Docker Compose Praxisguide: Lokale App, Postgres, Redis und Worker

Docker Compose ist der Bauplan für eine lokale Entwicklungsumgebung mit Web-App, PostgreSQL, Redis und Background Worker. Die offizielle Docker Compose Dokumentation beschreibt Compose als Werkzeug zum Definieren und Ausführen von Multi-Container-Anwendungen, inklusive Services, Netzwerken und Volumes in einer YAML-Datei.

Genau deshalb passt Compose gut zu Claude Code. Statt vage “mach mir ein Docker-Setup” zu fragen, gibst du Claude Code konkrete Dateien: compose.yaml, Dockerfile, .env.example und Makefile. Das Ergebnis ist prüfbar, reproduzierbar und leichter im Team zu erklären.

Masa hat dieses Muster in einem kleinen Next.js-Projekt mit Queue Worker getestet. Der Gewinn kam nicht durch einen besonderen Prompt, sondern durch klare Details: auf Postgres warten, Redis persistieren, node_modules schützen und Migration/Test-Kommandos an CI angleichen.

Dieser Guide liefert ein kopierbares Setup für app + PostgreSQL + Redis + worker. Compose ist stark für lokale Entwicklung, Integrationstests und Onboarding. Produktion ist eine eigene Entscheidung: Orchestrierung, Secrets, Monitoring, Backups, Security-Grenzen und Kosten müssen separat bewertet werden.

Architektur

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 bedient die Web-Anwendung. worker verarbeitet Hintergrundaufgaben wie E-Mails, Webhooks, Bildverarbeitung oder Queue Jobs. postgres und redis bekommen Healthchecks, damit abhängige Services auf echte Bereitschaft warten und nicht nur auf einen gestarteten Container.

Für die offizielle Syntax sind die Compose file reference und die services reference maßgeblich. Wenn Claude Code diese Quellen berücksichtigen soll, vermeidest du viele veraltete docker-compose-Beispiele.

Wo Compose passt

Einsatz	Warum Compose passt	Worauf achten
Lokale Entwicklung	App, DB, Redis und Worker starten mit einem Befehl	Mount-Performance unterscheidet sich je nach OS
Integrationstests	Test-DB und Redis lassen sich schnell erzeugen	Ports und Cache in CI explizit festlegen
Onboarding	.env.example und make setup standardisieren den Ablauf	Keine echten Secrets in Beispieldateien
Produktion	Für kleine interne Tools manchmal möglich	Security, Recovery, Skalierung, Monitoring und Kosten prüfen

Die Produktionsgrenze ist wichtig. Compose baut denselben Arbeitsplatz auf Entwickler-Maschinen. Für Produktion solltest du ECS, Kubernetes, Cloud Run, Fly.io, Render oder eure bestehende Plattform vergleichen. Bitte Claude Code eher um Migrationsrisiken als um einen direkten Produktionsplan aus der lokalen Datei.

Kopierbares compose.yaml

Das Beispiel geht von Node.js oder Next.js aus. Ersetze npm run dev, npm run worker:dev und die Migration-Skripte durch die Befehle aus deinem 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:

Drei Details sind entscheidend. Container erreichen einander über Service-Namen, also postgres:5432 und redis:6379, nicht localhost. node_modules liegt in einem named volume, damit der Bind Mount des Quellcodes die Container-Abhängigkeiten nicht überschreibt. Die doppelten Dollarzeichen im Postgres-Healthcheck sorgen dafür, dass die Variablen im Container ausgewertet werden.

Dockerfile

Ein Dockerfile mit getrennten Stages ist oft einfacher zu pflegen als mehrere Spezialdateien.

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

Der dev-Stage kopiert keinen Quellcode, weil Compose ihn mountet. Der build-Stage kopiert das vollständige Repository, damit CI und Produktionsimage unabhängig von deiner lokalen Maschine bauen.

.env.example

Committe .env.example, aber nicht .env. Die Beispieldatei zeigt die nötigen Variablen, ohne echte Zugangsdaten zu enthalten.

# .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 übergibt Variablen an Container. Die Compose-Interpolation liest zusätzlich die .env im Projekt. Halte diese beiden Verwendungen sauber getrennt und konsistent.

Makefile und Einmal-Kommandos

Ein kleines Makefile reduziert Missverständnisse im Alltag. Wenn dein Team kein make nutzt, verschiebe die Befehle in 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 verwendest du für bereits laufende Container. run --rm verwendest du für einmalige Befehle wie lint, test, migration oder seed. Dadurch ähneln lokale Befehle eher der CI.

Claude Code Review-Prompt

Die Claude Code common workflows empfehlen, Alltagsarbeit in kleine Schritte aufzuteilen: verstehen, ändern, testen, reviewen. Das gilt auch für Compose.

Reviewe die Docker Compose Konfiguration dieses Repositories.

Dateien:
- compose.yaml
- Dockerfile
- .env.example
- package.json
- CI workflows, falls vorhanden

Prüfe:
1. app + postgres + redis + worker laufen lokal
2. healthchecks und depends_on sind sinnvoll genutzt
3. named volumes und bind mounts sind sicher getrennt
4. .env.example enthält keine echten Secrets
5. migrate, seed, test und lint existieren als Einmal-Kommandos
6. CI-Risiken bei Ports, Cache, Rechten und Startup-Wartezeiten
7. was vor einem Produktionseinsatz separat geprüft werden muss

Vorgaben:
- bestehendes Framework und package manager respektieren
- große Refactorings nur vorschlagen
- bei Änderungen Grund und Prüfkommando nennen

Lege diesen Prompt in die Nähe von CLAUDE.md, damit das Team denselben Standard wiederholt. Passend dazu: Dev Container Guide und CI/CD Setup Guide.

Praktische Use Cases

Der erste Use Case ist Onboarding am ersten Tag. Wenn jemand .env.example kopiert und make up ausführt, sind App, DB, Redis und Worker verfügbar, ohne jedes Tool separat zu installieren.

Der zweite Use Case ist lokale Queue-Prüfung. E-Mail-Versand, Bildverarbeitung, Payment-Webhooks und Benachrichtigungen laufen oft im Worker. Mit worker in Compose kannst du echte Jobs reproduzieren.

Der dritte Use Case sind stabilere Integrationstests. Viele Fehler bestehen SQLite-Tests, fallen aber mit Postgres auf. Compose bringt Testumgebung und produktionsnahe DB näher zusammen.

Der vierte Use Case ist Infrastruktur-Review mit Claude Code. Menschen übersehen leicht localhost, alte Volumes, fehlende Healthchecks oder Secrets in Beispielen. Ein Review-Prompt macht daraus eine wiederholbare Checkliste.

Häufige Stolperfallen

Der häufigste Fehler ist eine DB-Verbindung zu localhost aus dem App-Container. Im Compose-Netzwerk sind Service-Namen die DNS-Namen. Verwende postgres und redis.

Der nächste Fehler ist, depends_on als vollständige Bereitschaftsgarantie zu verstehen. condition: service_healthy hilft, aber die App sollte DB-Verbindungen wiederholen, und der Worker darf kritische Jobs nicht vor Migrationen starten.

Alte named volumes erzeugen ebenfalls falsche Signale. Wenn sich das Schema ändert, aber postgres_data bleibt, passt dein lokaler Zustand nicht zum Repository. make clean setzt sauber zurück, löscht aber lokale Daten.

Setze keine echten API Keys in .env.example. Nutze Beispielwerte wie app_password oder replace_me; echte Secrets gehören in Docker secrets, Cloud Secret Manager oder CI Secrets.

Und schließlich: Nimm die lokale Compose-Datei nicht automatisch als Produktionsplan. Produktion braucht TLS, Netzwerkgrenzen, DB-Backup, Redis-Persistenz, Monitoring, Vulnerability Scan, Image-Herkunft, Rechte und Kostenkontrolle.

ClaudeCodeLab Training und Templates

Wenn du dieses Setup an dein Repository anpassen willst, starte mit den ClaudeCodeLab products and templates, um CLAUDE.md, Review-Prompts und Setup-Runbooks zu standardisieren. Wenn der schwierige Teil Team-Rollout, Docker-Desktop-Unterschiede, CI/CD, Rechte oder die Grenze zwischen Compose und Produktionsorchestrierung ist, nutze die Seite training and consultation.

Offizielle Referenzen: Docker Compose, Compose file reference, services reference und Claude Code common workflows.

Nach dem Testen der Inhalte aus diesem Artikel konnte Masas Beispielprojekt mit make up App, Postgres, Redis und Worker gemeinsam starten. Die Healthchecks reduzierten das typische Rennen, bei dem die App vor der Datenbank bereit ist. Die scharfe Kante waren alte named volumes: Sie können Migrationen falsch kaputt oder falsch repariert aussehen lassen. Fazit: Compose ist eine starke Grundlage für lokale Entwicklung, aber Produktion braucht eine separate Prüfung von Sicherheit, Betrieb, Wiederherstellung und Kosten.