Micha
a4f4696b0d
- REPO_MAP.md: replace Arbeitsregel with 8 binding documentation rules (one fact one home, done leaves the working copy, file types, header convention, quarterly gardening) - WORKFLOW.md Dokumentationspflicht and CLAUDE.md aligned to the rules - docs/README.md index rebuilt for the consolidated state - H drive docs merged into ops/h-drive-nearline/README.md (scheduled task + no-MIR rule added); docs/H_DRIVE_NEARLINE_PULL.md removed - implemented proposal archived to docs/archive/2026/ Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
64 lines
3.7 KiB
Markdown
64 lines
3.7 KiB
Markdown
# Repository Map
|
|
|
|
Stand: 2026-05-31
|
|
|
|
Kurzkarte des Repositories. Diese Datei ist bewusst kein zweites Handbuch; fuer
|
|
Details gilt immer die betroffene Compose-Datei oder das jeweilige Runbook.
|
|
|
|
## Top-Level
|
|
|
|
| Pfad | Zweck |
|
|
|---|---|
|
|
| `apps/` | produktive Anwendungen und vorbereitete App-Stacks |
|
|
| `core/` | Basisdienste, aktuell Gitea |
|
|
| `docs/` | aktive Betriebsdoku, Restore, Inventare, Arbeitsregeln |
|
|
| `env/` | nicht geheime Beispiel-Env-Dateien |
|
|
| `host-services/` | host-nahe Dienste mit direkten Ports oder Host-Netz |
|
|
| `infra/` | technische Infrastruktur wie PostgreSQL, Redis, DDNS |
|
|
| `monitoring/` | Prometheus, Grafana, Loki, InfluxDB 3 Core |
|
|
| `ops/` | Admin-, Backup-, Restore- und Wartungswerkzeuge |
|
|
| `security/` | Authelia, Vaultwarden und Security-Konfiguration |
|
|
| `services/` | Host-seitige Betriebsskripte und Recovery-Hilfen |
|
|
| `traefik/` | Reverse Proxy und dynamic File-Provider-Konfiguration |
|
|
|
|
## Einstiegspunkte
|
|
|
|
| Datei | Wann lesen |
|
|
|---|---|
|
|
| `README.md` | Repo-Einstieg |
|
|
| `HOMELAB_ARCHITECTURE_MASTER_V2.md` | Architektur, Netzmodell, Ausnahmen |
|
|
| `docs/WORKFLOW.md` | vor operativen Aenderungen |
|
|
| `docs/SERVICE_CATALOG.md` | Service-Zweck, Pfade, Besonderheiten |
|
|
| `docs/DISASTER_RECOVERY.md` | echter Wiederanlauf |
|
|
| `docs/RESTORE_MATRIX.md` | Restore-Quelle je Dienst |
|
|
| `docs/SECRETS_MAP.md` | Secret-Namen und Pfade ohne Werte |
|
|
| `docs/GITOPS_DRIFT_RUNBOOK.md` | Git/Gitea/Komodo/Docker/Host-Drift |
|
|
| `docs/MASTER_TODO.md` | einzige operative Statusliste |
|
|
| `docs/DECISIONS.md` | Entscheidungs-Register (ADR-light) |
|
|
| `docs/DR_WORKSTATION_SETUP.md` | Schritt-fuer-Schritt-Runbook fuer den DR-Gaming-PC (WSL2 + Borg-Client + SSH-Keys) |
|
|
| `docs/runbooks/komodo-bulk-deploy-dns.md` | Bulk-Deploy-Pulls scheitern an DNS, wenn AdGuard im selben Batch recreated wird |
|
|
|
|
## Wichtige Skripte
|
|
|
|
| Datei | Zweck |
|
|
|---|---|
|
|
| `ops/borg-ui/scripts/pre-backup-dumps.sh` | Dump-Erzeugung vor Borg |
|
|
| `ops/borg-ui/scripts/gitea-bundle-mirror.sh` | Gitea-Bundles fuer DR |
|
|
| `ops/restore-tests/run-restore-checks.sh` | Restore-Test-Einstieg |
|
|
| `ops/restore-tests/schedule.md` | Restore-Test-Kadenz |
|
|
| `services/posture-check/posture-check.sh` | Host-Posture-Check |
|
|
| `services/posture-check/export-prometheus-textfile.sh` | Borg-/Container-/Drift-Metriken |
|
|
| `services/authelia-diff.sh` | Authelia ACL Repo-zu-Host-Vergleich |
|
|
| `ops/h-drive-nearline/pull-critical-backups.ps1` | H:/ Nearline-Pull |
|
|
|
|
## Doku-Regeln
|
|
|
|
1. **Ein Fakt, ein Zuhause.** Status -> `docs/MASTER_TODO.md`; Entscheidungen -> `docs/DECISIONS.md`; Zielbild -> `HOMELAB_ARCHITECTURE_MASTER_V2.md`/Inventare/`SERVICE_CATALOG`; Ablauf -> genau ein Runbook; Beleg -> Host-Report (`/mnt/user/backups/restore-reports/`) oder Git-Commit. Alle anderen Stellen verlinken statt kopieren.
|
|
2. **Erledigt = raus aus der Arbeitskopie.** Abgeschlossene Plaene, Sprints, Audits und Drills nach `docs/archive/` (Belege mit Referenzwert) oder loeschen (Sprint-Boards, erledigte Listen) - Git ist das Archiv.
|
|
3. **Neue Datei nur mit klarem Typ:** Einstieg/Index, Architektur, Inventar/Referenz, Runbook, Entscheidung, Status oder befristeter Snapshot. Sonst ist es ein Eintrag in einer bestehenden Datei.
|
|
4. **Done-Eintraege max. 3 Zeilen**, Details in Commit/Report; Kurzlog in `MASTER_TODO` max. 5 Eintraege.
|
|
5. **Datum im Dateinamen nur fuer Snapshots**; datierte Dateien im `docs/`-Root sind per Definition Aufraeum-Kandidaten.
|
|
6. **Index-Pflicht:** jede neue/geloeschte Doku-Datei aktualisiert `docs/README.md` im selben Commit.
|
|
7. **Quartals-Gaertnern (~15 min):** Datiertes archivieren, Done-/Review-Logs kuerzen, tote Links pruefen.
|
|
8. **Kopfzeile je Dokument:** `Typ: ... · Stand: YYYY-MM-DD · Status: ...`. Bestandsnamen (SCREAMING_SNAKE) bleiben; neue Dateien in Unterordnern in kebab-case.
|