claude_settings/plans/elegant-zooming-porcupine.md

# 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