feat: INSTALL.md pro Stack im /docker-compose Skill

Phase 3 erweitert um einen Pflichtschritt 3e: INSTALL.md wird neben der
docker-compose.yaml im Stack-Verzeichnis erzeugt. Sie enthält
Voraussetzungen, Verzeichnis-Setup, .env-Befüllung, Start, Erst-Konfiguration,
Backup, Update inkl. Breaking-Change-Hinweisen aus Phase 0.5 sowie
Troubleshooting. Bei Updates wird die existierende INSTALL.md ergänzt,
nicht überschrieben.

Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>
This commit is contained in:
2026-06-16 08:04:29 +02:00
co-authored by Claude Opus 4.7
parent c640c5a575
commit 2eb4277aaa
+88 -3
View File
@@ -254,6 +254,7 @@ Wenn der User in Phase 0 als Zielhost `webserver` (waldperle) gewählt hat:
```
<stack-name>/
├── docker-compose.yaml
├── INSTALL.md (Schritt-für-Schritt-Anleitung)
├── .env (lokal, nicht in Git)
├── .env.example (Vorlage in Git)
├── .gitignore (mind. .env, dazu Daten-Verzeichnisse)
@@ -266,14 +267,98 @@ Generiere die `docker-compose.yaml` nach den Regeln aus Phase 1 + 2. Vor dem Sch
### 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`"
Nur als Hinweis an den User — nicht selbst per `mkdir` ausführen. Die konkreten Befehle landen in der `INSTALL.md` (3e).
### 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.
### 3e: `INSTALL.md` erzeugen (Pflicht)
Schritt-für-Schritt-Anleitung im Stack-Verzeichnis. Alle Installationshinweise des Skills landen hier — nicht als Chat-Output, sondern als Datei. Vorlage:
````markdown
# <Stack-Name> — Installation
Recherchiert: <YYYY-MM-DD>
Zielhost: <automation | controller | webserver | localhost>
## 1. Voraussetzungen
- Docker + Docker Compose v2 installiert
- Externe Netzwerke vorhanden (falls in Compose referenziert):
```bash
docker network ls | grep -E 'reverse-proxy|public|<weitere>'
# Falls fehlend:
docker network create reverse-proxy
```
## 2. Verzeichnis vorbereiten
```bash
cd /docker/<stack-name>
mkdir -p ./data ./db # alle persistenten Bind-Mounts aus dem Compose-File
chown -R 1000:1000 ./data ./db
```
## 3. .env befüllen
```bash
cp .env.example .env
chmod 600 .env
$EDITOR .env
```
Pflicht-Variablen:
- `<VAR_1>` — <Bedeutung, Format, Quelle (Passwort-Generator? KeePass?)>
- `<VAR_2>` — ...
## 4. Stack starten
```bash
docker compose config # Trockenlauf — keine Fehler erwartet
docker compose up -d
docker compose ps # alle Services healthy?
docker compose logs -f <service> # auf Initial-Output prüfen
```
## 5. Erst-Konfiguration
- Web-UI: `http://<host>:<port>` (bei webserver via VPN: `http://10.7.0.1:<port>`)
- Initial-Login: <falls dokumentiert — sonst Hinweis auf Setup-Wizard>
- Reverse-Proxy-Eintrag in NPM anlegen (falls reverse-proxy-Netz genutzt)
## 6. Backup
Persistente Verzeichnisse: `./data`, `./db`, `<weitere>`
Backup-Strategie: <restic? rsync? Hinweis auf zentrale Backup-Pipeline>
## 7. Update
```bash
docker compose pull
docker compose up -d
```
**Breaking Changes / Major-Upgrade-Hinweise:**
<aus Phase 0.5 — z.B. "PostgreSQL Major-Sprung erfordert pg_dumpall vorher">
## 8. Troubleshooting
- Logs: `docker compose logs <service>`
- Shell: `docker compose exec <service> sh`
- Vollständiger Reset (Achtung — Daten weg!): `docker compose down -v && rm -rf ./data ./db`
````
Befülle die Platzhalter aus den Phasen 0, 0.5, 1.5 und 2:
- Stack-Name, Zielhost, Recherche-Datum: aus Phase 0/0.5
- Pflicht-Variablen und ihre Bedeutung: aus der `.env.example` (3d)
- Breaking-Change-Hinweise: aus der Container-Recherche (Phase 0.5)
- Ports + Bind-IP-Beispiele: aus Phase 1.5 + 2 (bei webserver inkl. `10.7.0.1`)
- Persistente Verzeichnisse: aus den Bind-Mounts der Compose-Datei
Bei Update eines bestehenden Stacks: existierende `INSTALL.md` lesen, gezielt ergänzen — nicht überschreiben.
## Phase 4: Validierung
```bash