Docker Compose

Die Datei compose.yml bildet die zentrale technische Grundlage der Entwicklungsumgebung.

Während die devcontainer.json ausschließlich die Integration in VS Code beschreibt, definiert Docker Compose die vollständige Container-Architektur.

In der compose.yml werden deklarativ beschrieben:

• Container und deren Rollen
• Mount-Strategien für Workspace und Artefakte
• Volumes zur Persistenz von Dependencies und Tool-State
• Secrets zur sicheren Konfiguration
• Netzwerke und Port-Freigaben
• Hardening-Maßnahmen
• Startreihenfolgen und Abhängigkeiten

Die Konfiguration auf welcher diese Guideline aufbaut ist im Referenzprojekt zu finden.

Die Umgebung besteht aus mehreren Services (Container), die unterschiedliche Aufgaben übernehmen. Jeder Service entspricht einer konkreten technischen Umsetzung der zuvor definierten Container-Rollen.

Alle Services greifen auf denselben Sourcecode zu, jedoch mit unterschiedlichen:

• Mount-Rechten
• Sichtbarkeit einzelner Verzeichnisse
• Netzwerkzugriffen
• Secrets
• Laufzeitbeschränkungen

Die Services (Container) werden in einer definierten Reihenfolge gestartet. Vorbereitende Container stellen sicher, dass nachgelagerte Services in einem konsistenten Zustand arbeiten.

Typisches Beispiel:

• init-volumes erstellt benötigte Verzeichnisse und setzt Besitzrechte
• deps installiert Abhängigkeiten
• anschließend können dev, app oder ai auf denselben Zustand zugreifen

Die Steuerung erfolgt über depends_on mit Startbedingungen.

Die Container ai, ai-agent, app, deps und deps-update sind jeweils einem Compose-Profil zugeordnet.

compose.yml

deps:
  ...
  profiles: ["deps"]

Der Hauptzweck dieser Trennung ist, das unbeabsichtigte Starten situativer Container beim Öffnen des dev-Containers, bzw. bei Ausführung von docker compose up zu verhindern. Die klare Dokumentation der Service-Rollen und die Trennung der AI-Kontexte sind dabei hilfreiche Nebeneffekte.

dev und init-volumes haben bewusst kein Profil. Ein Profil würde den Standard-Workflow der VS Code Dev Container Extension stören.

Profiles erzwingen keine gegenseitige Exklusivität; beide Container können parallel gestartet werden.

In der Praxis ist das unproblematisch, da sie in getrennten Netzwerken laufen und keinen gemeinsamen schreibenden Zugriff außerhalb des claude_home-Volumes haben.