feat: /docker-compose Skill für Compose-Stacks nach Hausregeln
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>
This commit is contained in:
Claude Opus 4.7
@@ -0,0 +1,260 @@
|
||||
---
|
||||
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`:
|
||||
|
||||
| Ziel | SSH-Pfad | Netzwerk-Kontext |
|
||||
|---|---|---|
|
||||
| `automation` | `ssh automation:/docker/<name>/` | internes LAN, kein VPN-Binding |
|
||||
| `controller` | `ssh controller:/docker/<name>/` | internes LAN, kein VPN-Binding |
|
||||
| `webserver` | `ssh waldperle:/docker/<name>/` | öffentlich, interne Ports an VPN `10.7.0.1` binden |
|
||||
| `localhost` | aktuelles Arbeitsverzeichnis | kein Bind-Prefix |
|
||||
|
||||
4. **Reverse-Proxy** — soll der Stack über `nginx-proxy-manager` ans Web? Dann `reverse-proxy`-Netz nötig.
|
||||
5. **Persistente Daten** — welche Verzeichnisse müssen über Restarts/Recreates überleben (Datenbankdaten, Configs, Uploads, Logs)?
|
||||
6. **Gewünschte Host-Ports** — welche Ports sollen extern erreichbar sein? (werden in Phase 1.5 gegen Belegung geprüft)
|
||||
|
||||
Bei `webserver` zusätzlich:
|
||||
|
||||
> "Sollen die Ports nur über das VPN (`10.7.0.1`) erreichbar sein oder auch öffentlich (z.B. `80`, `443`)?"
|
||||
|
||||
Standardregel: **alle Ports an `10.7.0.1` binden**, nur explizit öffentliche (HTTP/HTTPS für reverse-proxy) bleiben ohne Bind-IP.
|
||||
|
||||
## Phase 1.5: Port-Belegungs-Analyse (Pflicht vor Generierung)
|
||||
|
||||
Bevor irgendein Port in die `docker-compose.yaml` geschrieben wird, **beide** Prüfungen auf dem Zielhost ausführen:
|
||||
|
||||
### Prüfung 1: Alle bestehenden Compose-Files
|
||||
|
||||
```bash
|
||||
# Bei automation/controller/webserver via SSH:
|
||||
ssh <host> "grep -rhE '^\s*-\s*\"?([0-9]+\.[0-9]+\.[0-9]+\.[0-9]+:)?[0-9]+:[0-9]+' /docker/ 2>/dev/null \
|
||||
| sed -E 's/.*\"?([0-9.]+:)?([0-9]+):.*/\2/' | sort -u"
|
||||
|
||||
# Bei localhost: lokal ausführen (Pfad ggf. anpassen)
|
||||
grep -rhE '^\s*-\s*\"?([0-9]+\.[0-9]+\.[0-9]+\.[0-9]+:)?[0-9]+:[0-9]+' . 2>/dev/null \
|
||||
| sed -E 's/.*\"?([0-9.]+:)?([0-9]+):.*/\2/' | sort -u
|
||||
```
|
||||
|
||||
### Prüfung 2: Aktive Listener auf dem Host
|
||||
|
||||
```bash
|
||||
ssh <host> "ss -tlnp 2>/dev/null | awk 'NR>1 {split(\$4, a, \":\"); print a[length(a)]}' | sort -u"
|
||||
# Bei localhost:
|
||||
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`).
|
||||
|
||||
### Multi-Service-Stacks
|
||||
|
||||
- **Healthchecks für DB/Cache:**
|
||||
```yaml
|
||||
healthcheck:
|
||||
test: ["CMD-SHELL", "pg_isready -U ${POSTGRES_USER}"]
|
||||
interval: 10s
|
||||
timeout: 5s
|
||||
retries: 5
|
||||
```
|
||||
- **`depends_on` mit `condition: service_healthy`** wo Healthchecks existieren — verhindert Race-Conditions beim Start.
|
||||
|
||||
### Image-Versionen
|
||||
|
||||
- **`:latest`** ist der Default (User-Wunsch: immer neueste Version).
|
||||
- Bei `:latest` + Watchtower-Enable=`true` → automatische Updates.
|
||||
- Bei kritischen Stacks (Datenbanken, Auth) kann ein gepinnter Tag sinnvoll sein — explizit beim User nachfragen.
|
||||
|
||||
### Security-Hardening (für exposed Services empfohlen)
|
||||
|
||||
```yaml
|
||||
cap_drop:
|
||||
- ALL
|
||||
security_opt:
|
||||
- no-new-privileges=true
|
||||
```
|
||||
|
||||
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):
|
||||
docker compose -f <pfad>/docker-compose.yaml config
|
||||
```
|
||||
|
||||
Erfolgreich heisst: keine Warnings, kein "version is obsolete", alle `${VAR}` auflösbar (mit gefüllter `.env`).
|
||||
|
||||
Bei Fehlern: korrigieren, erneut validieren.
|
||||
|
||||
## Phase 5: Test-Empfehlung
|
||||
|
||||
```bash
|
||||
# Trockenlauf
|
||||
docker compose -f <pfad>/docker-compose.yaml config
|
||||
|
||||
# Start
|
||||
cd <pfad> && docker compose up -d
|
||||
|
||||
# Logs prüfen
|
||||
docker compose logs -f <service>
|
||||
|
||||
# Status
|
||||
docker compose ps
|
||||
```
|
||||
|
||||
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