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:

# 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:

# 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

mkdir -p ~/Nextcloud/vinos
mkdir -p ~/Nextcloud/egonetix

Schritt 3: Infrastructure-Repo für vinos

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)

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)

# [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)

# [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