martin/claude-workflow
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

refactor: INSTALL.md nur mit stack-spezifischen Inhalten

Browse Source 
Die starre 8-Sektionen-Vorlage entfernt — sie enthielt viel Boilerplate
(Docker-Basics, generische compose-Befehle), der jeder Leser ohnehin kennt.
Neuer Ansatz: INSTALL.md listet nur das, was der Leser aus allgemeiner
Docker-Kenntnis nicht ableiten kann — konkrete Netze, Pfade, UIDs,
Pflicht-Env-Vars, Initial-Zugang, Reverse-Proxy-Setup, Major-Upgrade-Schritte,
stack-spezifisches Troubleshooting.

Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>
This commit is contained in:
martin
2026-06-16 08:06:32 +02:00
co-authored by Claude Opus 4.7
parent 2eb4277aaa
commit 58d6ed0b1c
1 changed files with 23 additions and 76 deletions
Download Patch File Download Diff File Expand all files Collapse all files
skills/docker-compose/SKILL.md
+23 -76
View File
@@ -275,89 +275,36 @@ Liste alle in der Compose-Datei referenzierten `${VARIABLE}` mit leerem Wert. So
### 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:
Die `INSTALL.md` enthält **nur stack-spezifische Inhalte** — alles, was der Leser nicht aus der allgemeinen Docker-Compose-Kenntnis weiss. Allgemeines (was Docker ist, dass `docker compose up -d` startet, dass `.env` aus `.env.example` kopiert wird) **nicht aufnehmen**.
````markdown
# <Stack-Name> — Installation
#### Was rein muss (sofern für den Stack zutreffend)
Recherchiert: <YYYY-MM-DD>
Zielhost: <automation | controller | webserver | localhost>
- **Header:** Stack-Name, Zielhost, Recherche-Datum (aus Phase 0/0.5)
- **Externe Netzwerke** dieses Stacks: konkrete Namen, die existieren müssen (`reverse-proxy`, `public`, `openhab`, …)
- **Persistente Verzeichnisse** dieses Stacks: exakte Pfade, erforderliche UID/GID, Sonderfälle (z.B. PostgreSQL braucht UID des Postgres-Users)
- **Pflicht-Env-Vars** dieses Stacks: was der Wert bedeutet, Format-Constraints, Generierungs-Hinweis (z.B. "32-Byte-Hex", "openssl rand -hex 32")
- **Initial-Zugang**: Default-Admin-Login, Setup-Wizard-URL, erstes Token aus den Logs ziehen — was dieses Image konkret macht
- **Reverse-Proxy-Einstellungen** für DIESEN Service: Ziel-Container + Port, Pfad-Besonderheiten, WebSocket-Pflicht, Trust-Proxy-Hops, spezielle Header
- **Ports und Erreichbarkeit** dieses Stacks: konkrete URLs, bei `webserver` mit `10.7.0.1` und Public-Variante
- **Backup-relevante Pfade** und stack-spezifische Pre-Backup-Schritte (z.B. `pg_dumpall` vor dem Volume-Backup)
- **Update-Besonderheiten** dieses Images (aus Phase 0.5): Major-Migrations-Skripte, deprecated Env-Vars die ersetzt werden müssen, Reihenfolge bei Multi-Service-Updates
- **Stack-spezifische Healthcheck-/Troubleshooting-Hinweise**: bekannte Fehler des Images, übliche Logmeldungen die Warnung sind aber keine Probleme, container-spezifische Reset-Schritte
## 1. Voraussetzungen
#### Was raus bleibt
- 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
```
- Wie man Docker installiert
- Generische `docker compose`-Befehle ohne stack-spezifischen Kontext
- "cp .env.example .env" und ähnliche Standardschritte
- Allgemeine Compose-Theorie
## 2. Verzeichnis vorbereiten
#### Quellen für den Inhalt
```bash
cd /docker/<stack-name>
mkdir -p ./data ./db # alle persistenten Bind-Mounts aus dem Compose-File
chown -R 1000:1000 ./data ./db
```
- Phase 0.5 (Container-Recherche) — Breaking Changes, Pflicht-Env-Vars, Volume-Pfade
- Phase 1.5 / 2 — Ports, VPN-Binding
- Compose-Datei selbst — Bind-Mounts, Netzwerke, depends_on-Reihenfolge
- Bei Lücken: erneut Doku des Images via Context7/WebFetch konsultieren, nicht raten
## 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.
Bei Update eines bestehenden Stacks: existierende `INSTALL.md` lesen, gezielt ergänzen — nicht überschreiben, keine Sektionen ohne neuen Inhalt einfügen.
## Phase 4: Validierung