Infrastruktur-Dokumentation: Neue Kunden-Organisation

- CLAUDE.md: Host-Troubleshooting → Infrastruktur-Dokumentationssystem - session-start.sh: Erkennt ~/Nextcloud/[kunde]/[repo]/ Struktur - Legacy-Support für ~/Nextcloud/hosts/ mit Migrations-Hinweis Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
2026-01-27 13:00:30 +01:00
parent 92b276a422
commit a536d35743
4 changed files with 772 additions and 81 deletions
--- a/plans/elegant-zooming-porcupine.md
+++ b/plans/elegant-zooming-porcupine.md
@@ -0,0 +1,373 @@
+# Plan: Infrastruktur-Dokumentationssystem
+
+## Ziel
+
+Ein wachsendes Dokumentationssystem das:
+1. **Alle Verbindungen** zwischen Diensten, Hosts und Hardware aufzeigt
+2. **Impact-Analyse** ermöglicht ("Was geht kaputt wenn ich X ändere?")
+3. **Änderungshistorie** bietet (Git-Log = Changelog)
+4. **Troubleshooting** unterstützt
+
+---
+
+## Architektur: Organisation pro Kunde
+
+```
+Gitea-Struktur:
+├── vinos/                       ← Organisation für Kunde "vinos"
+│   ├── infrastructure.git       ← Landkarte für vinos
+│   ├── zabbix.git               ← System-Repo
+│   ├── pmg-mailgw.git           ← System-Repo
+│   └── n8n.git                  ← Dienst-Repo
+│
+└── egonetix/                    ← Organisation für Kunde "egonetix"
+    ├── infrastructure.git       ← Landkarte für egonetix
+    ├── pfsense.git
+    └── traefik.git
+```
+
+```
+Lokal:
+~/Nextcloud/
+├── vinos/                       ← Kunde vinos
+│   ├── infrastructure/          ← Landkarte
+│   ├── zabbix/                  ← System-Repo
+│   ├── pmg-mailgw/              ← System-Repo
+│   └── n8n/                     ← Dienst-Repo
+│
+└── egonetix/                    ← Kunde egonetix
+    ├── infrastructure/
+    ├── pfsense/
+    └── traefik/
+```
+
+| Repo-Typ | Gitea-Ort | Inhalt |
+|----------|-----------|--------|
+| **Infrastructure** | `[kunde]/infrastructure.git` | Landkarte, Abhängigkeiten für diesen Kunden |
+| **System-Repo** | `[kunde]/[system].git` | Konfig-Dateien, README, Troubleshooting |
+| **Dienst-Repo** | `[kunde]/[dienst].git` | docker-compose.yml, Code, Workflows |
+
+**Vorteile:**
+- Klare Kunden-Trennung
+- Jeder Kunde hat eigene Infrastruktur-Doku
+- Repos sind nach Kunde gruppiert auf Gitea
+- Zugriffsrechte pro Organisation möglich
+
+---
+
+## 1. Infrastructure-Repo (NEU) - SCHLANK
+
+**Speicherort:** `~/Nextcloud/infrastructure/` → `ssh://git@gitea.egonetix.de:222/root/infrastructure.git`
+
+**Prinzip:** Nur Landkarte und Links - KEINE Konfig-Dateien!
+
+```
+infrastructure/
+├── README.md                 ← Einstieg + Gesamtübersicht
+├── hosts/
+│   ├── srvdocker02.md        ← Übersicht + Links zu Dienst-Repos
+│   ├── srv-monitor02.md      ← Übersicht + Link zu systems/zabbix.git
+│   └── pmg01.md              ← Übersicht + Link zu systems/pmg-mailgw.git
+├── netzwerk/
+│   ├── vlans.md
+│   └── dns.md
+├── hardware/
+│   ├── switches.md
+│   ├── firewalls.md
+│   └── storage.md
+└── dependencies.md           ← HERZSTÜCK: Mermaid-Diagramme
+```
+
+**Beispiel hosts/pmg01.md:**
+```markdown
+# PMG01 - Proxmox Mail Gateway
+
+| IP | Funktion | Repo |
+|----|----------|------|
+| 10.0.0.50 | Mail-Gateway | [systems/pmg-mailgw](https://gitea.egonetix.de/systems/pmg-mailgw) |
+
+## Abhängigkeiten
+- **Betrifft:** mailsrv1, mailsrv2
+- **Benötigt:** DNS, Internet
+
+→ Details und Konfig: siehe [Repo](https://gitea.egonetix.de/systems/pmg-mailgw)
+```
+
+### dependencies.md Beispiel:
+
+```markdown
+# Abhängigkeiten
+
+## Mail-System
+```mermaid
+graph LR
+    Internet --> pmg01[PMG Mailgateway]
+    pmg01 --> mailsrv1[Mailserver 1]
+    pmg01 --> mailsrv2[Mailserver 2]
+    mailsrv1 --> storage[(NAS01)]
+    mailsrv2 --> storage
+```
+
+**Impact:** Änderung an PMG betrifft beide Mailserver!
+
+## Monitoring
+```mermaid
+graph TD
+    zabbix[Zabbix] -.überwacht.-> pmg01
+    zabbix -.überwacht.-> srvdocker02
+    zabbix -.überwacht.-> pfsense
+    zabbix --> postgres[(PostgreSQL)]
+```
+```
+
+---
+
+## 2. Dienst-Repos (Docker) - BEHALTEN
+
+**Beispiel:** n8n, trading-bot, traefik
+
+**Struktur:**
+```
+n8n/
+├── docker-compose.yml
+├── Dockerfile (optional)
+├── .env.example
+├── README.md              ← Deployment, Zugang, Quick Reference
+├── scripts/
+└── config/
+```
+
+**Git-Log = Changelog:**
+```
+a3f2b1c Webhook-URL geändert (betrifft: Telegram-Bot)
+e7d4a9f PostgreSQL auf Version 15 aktualisiert
+```
+
+---
+
+## 3. System-Repos (Appliances/VMs) - NEU
+
+**Für:** PMG, pfSense, Mailserver, Zabbix-Server, etc.
+
+**Struktur:**
+```
+pmg-mailgw/
+├── README.md              ← Zugang, IP, Quick Reference
+├── config/                ← Konfig-Dateien direkt (Git = Backup!)
+│   ├── cluster.conf
+│   ├── relay_domains
+│   └── main.cf
+├── dependencies.md        ← "betrifft: mailsrv1, mailsrv2"
+└── troubleshooting.md     ← Bekannte Probleme & Lösungen
+```
+
+**Workflow bei Änderungen:**
+1. Änderung am System durchführen
+2. Konfig-Dateien ins Repo kopieren
+3. `git commit -m "Relay-Domain hinzugefügt (betrifft: mailsrv1, mailsrv2)"`
+4. Bei Problem: `git log` → sofort sichtbar was sich geändert hat
+
+---
+
+## Was wird aus dem bisherigen Setup?
+
+| Alt | Neu |
+|-----|-----|
+| `~/Nextcloud/hosts/` | → `~/Nextcloud/infrastructure/` |
+| `~/Nextcloud/hosts/_templates/` | → Templates pro Repo-Typ |
+| Host-Repos (vinos_srv-monitor02) | → System-Repos oder nur im Infrastructure-Repo |
+| Dienst-Repos (n8n) | Bleiben wie sie sind |
+
+---
+
+## Dateien zu erstellen/ändern
+
+### Schritt 1: Gitea-Organisationen anlegen
+
+```
+https://gitea.egonetix.de/org/create
+- "vinos" anlegen
+- "egonetix" anlegen
+```
+
+### Schritt 2: Lokale Verzeichnisstruktur
+
+```bash
+mkdir -p ~/Nextcloud/vinos
+mkdir -p ~/Nextcloud/egonetix
+```
+
+### Schritt 3: Infrastructure-Repo für vinos
+
+```bash
+cd ~/Nextcloud/vinos
+git init infrastructure
+cd infrastructure
+```
+
+| Datei | Beschreibung |
+|-------|--------------|
+| `README.md` | Einstiegspunkt für vinos |
+| `dependencies.md` | Mermaid-Diagramme (Mail-System, Monitoring, etc.) |
+| `hosts/` | Host-Übersichten (kurz, mit Links zu Repos) |
+| `netzwerk/` | VLANs, DNS, Firewall-Regeln |
+| `hardware/` | Switches, Storage, Server-Hardware |
+| `_templates/` | Templates für neue Hosts/Systeme |
+
+Remote: `ssh://git@gitea.egonetix.de:222/vinos/infrastructure.git`
+
+### Schritt 4: Zabbix System-Repo (Migration)
+
+```bash
+cd ~/Nextcloud/vinos
+git init zabbix
+cd zabbix
+```
+
+| Datei | Beschreibung |
+|-------|--------------|
+| `README.md` | Zugang, Quick Reference (migriert von srv-monitor02) |
+| `config/` | Relevante Konfig-Dateien |
+| `troubleshooting.md` | Bekannte Probleme & Lösungen |
+| `dependencies.md` | "Überwacht: alle Hosts" |
+
+Remote: `ssh://git@gitea.egonetix.de:222/vinos/zabbix.git`
+
+### Schritt 5: Claude-Settings aktualisieren
+
+| Datei | Änderung |
+|-------|----------|
+| `~/.claude/CLAUDE.md` | Neue Struktur mit Kunden-Organisationen |
+| `session-start.sh` Hook | `~/Nextcloud/[kunde]/` erkennen |
+| `troubleshoot.md` Skill | Anpassen auf neue Struktur |
+| NEU: `new-repo.md` Skill | Neues System-/Dienst-Repo für Kunden anlegen |
+
+### Schritt 6: Aufräumen
+
+| Datei | Aktion |
+|-------|--------|
+| `~/Nextcloud/hosts/` | Löschen nach Migration |
+| `root/vinos_srv-monitor02.git` | Optional: Archivieren (kann auch bleiben) |
+
+**Nicht jetzt:** Bestehende Repos (n8n, etc.) bleiben unter `root/` - Migration zu egonetix später
+
+---
+
+## Templates
+
+### Template: Dienst (Docker)
+
+```markdown
+# [DIENST-NAME]
+
+## Quick Start
+```bash
+docker-compose up -d
+```
+
+## Zugang
+- URL: https://[domain]
+- Port: [port]
+
+## Abhängigkeiten
+- Benötigt: [PostgreSQL, Redis, etc.]
+- Wird genutzt von: [andere Dienste]
+
+## Konfiguration
+[Wichtige Umgebungsvariablen, Volumes]
+
+## Troubleshooting
+[Häufige Probleme]
+```
+
+### Template: System (Appliance/VM)
+
+```markdown
+# [SYSTEM-NAME]
+
+## System Overview
+| Eigenschaft | Wert |
+|-------------|------|
+| **Host** | [hostname] |
+| **IP** | [ip] |
+| **Typ** | [Proxmox/VMware/Bare-Metal] |
+| **OS** | [Debian/FreeBSD/etc.] |
+| **Zugang** | [SSH/Web-UI] |
+
+## Abhängigkeiten
+**Dieses System betrifft:**
+- [system1]
+- [system2]
+
+**Dieses System benötigt:**
+- [dependency1]
+
+## Konfig-Dateien
+| Datei | Beschreibung |
+|-------|--------------|
+| config/[file] | [was es tut] |
+
+## Wichtige Befehle
+```bash
+# [Beschreibung]
+[befehl]
+```
+
+## Troubleshooting
+[Bekannte Probleme & Lösungen]
+```
+
+---
+
+## Verifikation
+
+1. [ ] Gitea-Organisation "vinos" existiert
+2. [ ] `vinos/infrastructure.git` angelegt und gepusht
+3. [ ] `vinos/zabbix.git` angelegt (Inhalt von srv-monitor02)
+4. [ ] Mindestens ein Mermaid-Diagramm in `vinos/infrastructure/dependencies.md`
+5. [ ] Claude in `~/Nextcloud/vinos/zabbix/` starten → Lädt README
+6. [ ] `~/Nextcloud/hosts/` gelöscht
+7. [ ] CLAUDE.md und Hooks aktualisiert für neue Struktur
+
+**Später:** egonetix Organisation + Migration bestehender Repos
+
+---
+
+## Entscheidungen (geklärt)
+
+| Frage | Entscheidung |
+|-------|--------------|
+| Kunden-Trennung | Organisation pro Kunde (`vinos/`, `egonetix/`) |
+| Infrastructure-Repo | Schlank - nur Landkarte, keine Configs (pro Kunde) |
+| Namenskonvention | `[kunde]/[name].git` (z.B. `vinos/zabbix.git`) |
+| srv-monitor02 | Migrieren → `vinos/zabbix.git` |
+| Hardware | Im jeweiligen Kunden-Infrastructure-Repo |
+
+---
+
+## Migration
+
+### Jetzt:
+
+1. **Gitea-Organisationen anlegen**
+   - `vinos` Organisation erstellen
+   - `egonetix` Organisation erstellen (für später)
+
+2. **vinos Infrastructure-Repo anlegen**
+   - Neues Repo: `vinos/infrastructure.git`
+   - Basis-Struktur mit hosts/, dependencies.md, etc.
+
+3. **vinos/zabbix.git anlegen** (migriert von srv-monitor02)
+   - Inhalt von `vinos_srv-monitor02` übernehmen
+   - Altes Repo kann bleiben oder archiviert werden
+
+4. **Lokale Struktur**
+   - `~/Nextcloud/vinos/infrastructure/`
+   - `~/Nextcloud/vinos/zabbix/`
+   - `~/Nextcloud/hosts/` entfernen
+
+### Später (nicht Teil dieses Plans):
+
+- Bestehende Repos unter `root/` (n8n, etc.) → gehören zu egonetix
+- Migration in `egonetix/` Organisation wenn Zeit ist
+- Diese Repos bleiben erstmal wo sie sind