Skill fragt vier Zielhosts ab (automation, controller, webserver, localhost),
prüft Port-Belegung gegen bestehende Compose-Files und aktive Listener und
generiert eine docker-compose.yaml plus .env nach den Hausregeln (5 MB Logging,
TZ Berlin, relative Bind-Mounts, Secrets in .env). Auf webserver werden interne
Ports an die VPN-IP 10.7.0.1 gebunden.
Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>
2026-06-16 07:53:58 +02:00
3 changed files with 262 additions and 1 deletions
description:Erstellt oder aktualisiert eine docker-compose.yaml nach den Best Practices dieses Workflows — aktuelle Compose-Syntax, explizite Konfiguration, Secrets in .env, optionales VPN-Binding für den Webserver. Aktivieren wenn ein neuer Container-Stack aufgesetzt oder ein bestehender überarbeitet werden soll. Nicht verwenden für reine Image-Updates, einzelne docker-Befehle oder Dockerfile-Änderungen.
model:claude-opus-4-6
---
# /docker-compose — Compose-Stack nach Hausregeln
Zielort: ein Verzeichnis unter `/docker/<name>/` auf einem der Hosts oder lokal. Der Skill liefert eine `docker-compose.yaml` plus passende `.env`-Vorlage.
## Phase 0: Aufgabenklärung
Stelle dem User folgende Fragen, sofern nicht schon im Request beantwortet:
1.**Name des Stacks** (Verzeichnisname unter `/docker/`)
2.**Welche Services** sind enthalten (Image + Zweck)?
3.**Zielhost** — eine der folgenden vier Optionen, per `AskUserQuestion`:
ss -tlnp 2>/dev/null | awk 'NR>1 {split($4, a, ":"); print a[length(a)]}'| sort -u
```
### Konfliktauflösung
Vergleiche die in Phase 0 gewünschten Host-Ports mit beiden Listen:
- **Frei in beiden:** Port übernehmen.
- **Belegt in Prüfung 1 (Compose):** zeigen, welcher Stack/Service belegt — User fragen, ob Konflikt akzeptiert ist (selten korrekt) oder ein anderer Port gewählt werden soll.
- **Belegt in Prüfung 2 (Listener):** zeigen welcher Prozess — alternativen Port vorschlagen.
- **Vorschlag bei Konflikt:** nächste freie Port-Nummer aus passendem Bereich (Web-UIs `8000–8999`, DBs `5400+`, Custom `3000–3999`).
Erst wenn alle gewünschten Ports konfliktfrei sind, weiter zu Phase 3.
**Hinweis für `webserver`:** das VPN-IP-Prefix `10.7.0.1` ändert nichts an der Belegungsprüfung — ein bereits gebundener Port ist gebunden, egal an welche IP.
## Phase 1: Pflichtregeln (nicht verhandelbar)
Diese Regeln gelten für jeden generierten Stack:
### Compose-Syntax
- **Kein `version:`-Key.** Compose v2 ignoriert ihn — nicht aufnehmen.
- **`name: <stack>`** als oberstes Feld (Project-Name explizit setzen).
- **YAML-Mapping-Stil konsistent** pro Datei (entweder Listen-Stil `- KEY=VAL` oder Map-Stil `KEY: VAL` — nicht mischen innerhalb eines Services).
### Pro Service
- **`container_name: <name>`** — explizit, stabile Namen für Logs/Scripts.
- **`hostname: <name>`** — für interne Service-Adressierung in geteilten Netzwerken.
- **`restart: unless-stopped`** als Default. `always` nur wenn der Container nach einem manuellen `docker stop` von alleine wieder hochkommen soll.
- **`environment:`**
-`TZ=Europe/Berlin` ist Pflicht.
- Alle relevanten Env-Variablen explizit auflisten (keine impliziten Defaults aus dem Image — der Image-Default kann sich ändern).
- Sensible Werte (Passwörter, Tokens, Secrets, API-Keys) ausschließlich als `${VARIABLE}` referenzieren — Werte in `.env`.
- Keine Inline-Defaults vom Typ `${VAR:-default}` für Secrets. Für nicht-sensible Werte erlaubt, aber sparsam.
- **`logging:`**
```yaml
logging:
driver: "json-file"
options:
max-size: "5M"
max-file: "3"
```
5 MB pro Datei × 3 Dateien = max. 15 MB pro Container.
- **`labels:`**
```yaml
labels:
- "com.centurylinklabs.watchtower.enable=false"
```
Default `false` (entspricht globaler CLAUDE.md). Auf `true` setzen, wenn der Container über `:latest` läuft und automatische Updates erwünscht sind.
- **`user: "1000:1000"`** als Default. Ausnahmen nur, wenn das Image Root erfordert (z.B. NPM Port 80/443) — dann mit Kommentar warum.
- **Volumes als relative Bind-Mounts** (`./data:/data`). Niemals absolute Pfade ausserhalb von `./`, niemals named volumes für Datenpersistenz (Backup-Strategie hängt am Bind-Mount).
- **Read-only mounten** wo möglich (`./config:/etc/app/config:ro`).
### Ports
- **Immer als gequoteter String:** `"8080:80"`. Unquoted YAML kann `5060:5060` als Sexagesimalzahl interpretieren.
- **Pro Zielhost:**
- `automation`, `controller`, `localhost`: kein IP-Prefix (LAN-intern erreichbar).
- `webserver` (waldperle): alle internen Ports an `10.7.0.1` binden — `"10.7.0.1:8080:80"`. Nur explizit öffentliche Ports (NPM 80/443) ohne IP-Prefix.
- **Belegung muss in Phase 1.5 geprüft sein** — kein Port ohne vorherige Konfliktprüfung.
### Netzwerke
- **Externe Standard-Netze:**
- `reverse-proxy` — für alle Container, die über NPM ans Web sollen
- `public` — für Container mit direktem Public-Exposure
- `openhab` — Smart-Home-Stack (nur `automation`)
- Externe Netze in der `networks:`-Sektion immer mit `external: true` markieren.
- Stack-interne Netze ohne `external` deklarieren (oder weglassen — Compose erzeugt dann `<name>_default`).
Aufnehmen für: Web-UIs, REST-APIs, alles was Ports öffnet. Nicht für DBs/Caches im internen Netz (würde dort oft brechen).
### `.env`-Datei
- Liegt im selben Verzeichnis wie die `docker-compose.yaml`.
- Wird per `.gitignore` ausgeschlossen.
- Eine `.env.example` ohne Werte mitliefern — als Vorlage.
- Format:
```
# Pflicht
DB_USER=
DB_PASSWORD=
# ...
```
## Phase 2: VPN-Binding für Webserver-Stacks
Wenn der User in Phase 0 als Zielhost `webserver` (waldperle) gewählt hat:
1. **Bind-Adresse abfragen** falls nicht bekannt:
> "Welche VPN-Interface-IP soll gebunden werden? (Standard `waldperle`: `10.7.0.1`)"
2. **Pro Service-Port entscheiden:**
- Public (im Internet erreichbar, typisch Reverse-Proxy 80/443): ohne IP-Prefix.
- Alle anderen Ports (Web-UIs, DBs, Admin-Interfaces, Metrics): an die VPN-IP binden.
3. **Begründung im Kopf des Compose-Files als Kommentar dokumentieren:**
```yaml
# Webserver-Stack — interne Ports nur via VPN (10.7.0.1) erreichbar.
# Nur 80/443 (Reverse-Proxy) sind öffentlich exponiert.
```
## Phase 3: Generierung
### 3a: Verzeichnis-Layout
```
<stack-name>/
├── docker-compose.yaml
├── .env (lokal, nicht in Git)
├── .env.example (Vorlage in Git)
├── .gitignore (mind. .env, dazu Daten-Verzeichnisse)
└── <persistente Verzeichnisse, z.B. ./data, ./db, ./config>
```
### 3b: Datei erzeugen
Generiere die `docker-compose.yaml` nach den Regeln aus Phase 1 + 2. Vor dem Schreiben prüfen, ob die Datei schon existiert — bei Update nur die nötigen Felder anfassen, vorhandene Kommentare/Strukturen erhalten.
### 3c: Persistente Verzeichnisse anlegen
Nur als Hinweis an den User — nicht selbst per `mkdir` ausführen. Beispiel:
> "Vor dem ersten Start: `mkdir -p ./data ./db && chown -R 1000:1000 ./data ./db`"
### 3d: `.env.example` erzeugen
Liste alle in der Compose-Datei referenzierten `${VARIABLE}` mit leerem Wert. Sortierung: erst Pflicht, dann optional. Jede Variable mit Einzeiler-Kommentar, wozu sie dient.
## Phase 4: Validierung
```bash
# Auf dem Zielhost (automation/controller/webserver via SSH, oder lokal):
Warte auf User-Rückmeldung, ob der Stack erfolgreich gestartet ist.
## Phase 6: Abschluss via /ship
Wenn die Compose-Datei in einem Git-Repo liegt: `/ship` aufrufen.
Liegt sie nur lokal auf dem Host (z.B. direkt unter `/docker/<name>/` auf `automation`/`waldperle`, ohne Git): User erinnern, die Konfiguration manuell ins Backup aufzunehmen.
## Pitfalls — explizite Verbote
- Kein `version:`-Key (obsolet).
- Keine impliziten Image-Defaults für relevante Konfiguration.
- Keine ungequoteten Port-Mappings.
- Keine absoluten Pfade in Bind-Mounts.
- Keine Secrets im Klartext in der Compose-Datei.
- Keine named Volumes für persistente Daten.
- Auf `webserver` (waldperle): kein ungebundener interner Port — sonst public.
- Keine Port-Angabe ohne vorherige Belegungs-Analyse aus Phase 1.5.
Reference in New Issue
Block a user
Blocking a user prevents them from interacting with repositories, such as opening or commenting on pull requests or issues. Learn more about blocking a user.
martinandClaude Opus 4.7