Claude Code und Docker: Compose, Volumes, Netzwerke und CI-Builds

Erst festlegen, was Claude Code tun soll

Wenn man Claude Code nur “mach Docker daraus” sagt, entsteht oft ein Dockerfile, das einmal startet, aber schwer zu pruefen ist. Docker fixiert die Laufzeitumgebung einer Anwendung: Ein Image ist die Vorlage, ein Container ist die laufende Instanz, ein Volume speichert Daten ausserhalb des Containers, und ein Netzwerk erlaubt Services, sich per Namen zu erreichen.

In echten Projekten ist das Dockerfile nur ein Teil. Pruefen Sie Dockerfile, docker-compose.yml, .dockerignore, Umgebungsvariablen, Health Checks und CI-Build zusammen. Nutzen Sie die offiziellen Quellen: Dockerfile reference, Compose file reference, Docker build best practices, Docker Build GitHub Actions und Claude Code overview.

Fuer den Gesamtprozess passen Claude Code CI/CD setup, approval and sandbox guide und security best practices dazu.

Konkrete Einsatzfaelle

Docker hilft, wenn es Unsicherheit aus dem Alltag nimmt. Benennen Sie zuerst das Problem.

Einsatzfall	Was Docker standardisiert	Auftrag an Claude Code
Onboarding neuer Entwickler	Node.js, PostgreSQL, Redis, Ports, Startbefehle	docker compose up soll den Stack starten
Produktionsnahe Fehlersuche	Variablen, Service-Namen, Health Checks, Startreihenfolge	Unterschiede zwischen lokal und Produktion auflisten
PR-Pruefung	Dockerfile, Lockfile, Build-Cache, CI-Logs	Workflow ergaenzen, der nur das Image baut
Training und Uebergabe	Befehle, Fehlerbilder, Recovery	Regeln in CLAUDE.md und README schreiben

Bei SaaS- oder Content-Projekten mit Umsatz ist das keine Kosmetik. Checkout, Lead-Formulare, Admin-Screens und Produktseiten duerfen nicht von einem Laptop abhaengen. Einzelpersonen starten mit ClaudeCodeLab products. Teams, die Regeln, Rechte, CI und Reviews an ihr Repository anpassen wollen, nutzen Claude Code training and consultation.

Prompt mit klaren Grenzen

Der erste Prompt sollte Ziel, erwartete Dateien, Verbote und Verifikation enthalten. So vermeiden Sie ein plausibles, aber unsicheres 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.

Ein Multi-Stage-Build trennt Build-Umgebung und Runtime. TypeScript-Werkzeuge bleiben im Build-Stage, das finale Image enthaelt nur Produktionsabhaengigkeiten und dist.

Dockerfile zum Kopieren

Das Beispiel nimmt eine Node.js API an, die src/index.ts nach dist/index.js baut. Der Stage dev ist fuer Compose lokal, runner ist das Produktionsimage.

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

Lassen Sie Claude Code drei Dinge pruefen: koennen Secrets ins Image gelangen, bleibt der Cache durch die COPY-Reihenfolge nutzbar, und sind devDependencies aus dem Runtime-Image entfernt.

Compose: Volumes und Netzwerke

Compose startet mehrere Container zusammen. API, PostgreSQL und Redis teilen ein Netzwerk; die API erreicht postgres und redis per Service-Namen. Volumes halten Daten ausserhalb kurzlebiger Container. pgdata speichert die Datenbank, api_node_modules verhindert, dass Host-Module Linux-Abhaengigkeiten ueberschreiben.

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 steuert die Startreihenfolge. Es beweist nicht automatisch, dass die Datenbank Verbindungen annimmt. Deshalb werden Health Checks und condition: service_healthy kombiniert.

Secrets aus dem Build-Kontext halten

Beginnen Sie mit .dockerignore. Das reduziert den Build-Kontext und verhindert, dass .env versehentlich kopiert wird.

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

Ergaenzen Sie anschliessend gemeinsame Scripts in package.json.

{
  "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"
  }
}

Wiederholbares Pruefskript

Manuelle Checks werden vergessen. Legen Sie den Ablauf in scripts/docker-check.sh ab.

#!/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

Das Skript baut das API-Image, startet den Stack, wartet auf /health und zeigt Logs, falls der Service nicht gesund wird.

CI: Erst bauen, spaeter pushen

Im ersten PR reicht es, den Image-Build zu verifizieren. Push, Signatur, Vulnerability Scan und SBOM koennen spaeter folgen.

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 sollte erklaeren, ob dieser Workflow pusht, ob die Rechte zu gross sind und was ohne Cache passiert.

Haeufige Fehler

Der teuerste Fehler ist das Kopieren von .env in das Image. Sobald ein Secret in einem Registry landet, wird die Bereinigung aufwendig. Pruefen Sie .dockerignore, CI-Secrets und Build-Logs zusammen.

Ein weiterer Fehler ist das Mounten von Host-node_modules in einen Linux-Container. Native Module unterscheiden sich zwischen macOS, Windows und Linux. Ein benanntes Volume trennt diese Welten.

Auch Start-Races sind typisch: Die API startet, bevor PostgreSQL bereit ist. Nutzen Sie Health Checks und Retry-Logik in der Anwendung.

Fuehren Sie Produktion ausserdem nicht als root aus. Das wirkt in Demos harmlos, vergroessert aber die Auswirkung einer Schwachstelle. Claude Code soll die genauen Dockerfile-Zeilen zeigen, die non-root beweisen.

Sicherer Arbeitsablauf

Die Reihenfolge sollte sein: Repository inspizieren, Runtime-Abhaengigkeiten sammeln, .dockerignore schreiben, lokales Compose erstellen, Produktions-Dockerfile erstellen, Pruefskript hinzufuegen, dann CI. Nach jedem Schritt liest ein Mensch git diff, und Claude Code liefert vier kurze Punkte: geaenderte Dateien, Grund, Verifikationsbefehl, verbleibendes Risiko.

Dieser Ablauf passt gut zu session handoff template. Docker-Integration sollte eine wiederholbare Teamgewohnheit werden, nicht ein einmal generiertes File.

Ergebnis aus der Praxis

In der Praxis wurden die Ergebnisse besser, wenn Claude Code kleine Aufgaben bekam. .dockerignore, dann Compose, dann Health Checks, dann CI erzeugte besser pruefbare Diffs. Das benannte api_node_modules-Volume und service_healthy fuer die Datenbank verhinderten zwei typische Anfaengerprobleme: “funktioniert nur bei mir” und “API startet, verbindet sich aber nicht mit Postgres”.