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:
@@ -254,6 +254,7 @@ Wenn der User in Phase 0 als Zielhost `webserver` (waldperle) gewählt hat:
|
|||||||
```
|
```
|
||||||
<stack-name>/
|
<stack-name>/
|
||||||
├── docker-compose.yaml
|
├── docker-compose.yaml
|
||||||
|
├── INSTALL.md (Schritt-für-Schritt-Anleitung)
|
||||||
├── .env (lokal, nicht in Git)
|
├── .env (lokal, nicht in Git)
|
||||||
├── .env.example (Vorlage in Git)
|
├── .env.example (Vorlage in Git)
|
||||||
├── .gitignore (mind. .env, dazu Daten-Verzeichnisse)
|
├── .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
|
### 3c: Persistente Verzeichnisse anlegen
|
||||||
|
|
||||||
Nur als Hinweis an den User — nicht selbst per `mkdir` ausführen. Beispiel:
|
Nur als Hinweis an den User — nicht selbst per `mkdir` ausführen. Die konkreten Befehle landen in der `INSTALL.md` (3e).
|
||||||
|
|
||||||
> "Vor dem ersten Start: `mkdir -p ./data ./db && chown -R 1000:1000 ./data ./db`"
|
|
||||||
|
|
||||||
### 3d: `.env.example` erzeugen
|
### 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.
|
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
|
## Phase 4: Validierung
|
||||||
|
|
||||||
```bash
|
```bash
|
||||||
|
|||||||
Reference in New Issue
Block a user