Struktur der Dokumentation

Diese Seite hält nur die vereinbarte Struktur fest. Sie beschreibt den Aufbau, nicht die technischen Inhalte der einzelnen Dienste.

1. Einstieg und Übersicht

Am Anfang steht eine zentrale Übersichtsseite. Sie dient gleichzeitig als Inhaltsverzeichnis und als Diensteregister.

Sie enthält pro relevantem Hauptdienst:

• Name des Dienstes
• Kategorie
• öffentliche Subdomain oder Hostnamen
• Link zur passenden Dokumentationsseite

Die Übersicht soll später gut als Startseite einer generierten HTML-Dokumentation funktionieren.

2. Konzeptseiten

Nach der Übersicht folgen grundlegende Konzeptseiten. Sie erklären systemweite organisatorische Prinzipien, ohne einzelne Dienste unnötig doppelt zu dokumentieren.

Vorgesehene Konzeptbereiche:

• Serverstruktur
• Subdomain Registry und Caddy-Generierung
• Docker-Stack-Konventionen
• Secrets, persistente Daten und Backups

Die Konzeptseiten beschreiben das Prinzip. Die konkrete Umsetzung eines Dienstes steht auf der jeweiligen Dienstseite.

3. Agenten

Hermes und OpenClaw werden als eigener Abschnitt dokumentiert. Sie sind Teil der Infrastruktur, aber keine normalen Docker-Hauptdienste.

Reihenfolge:

1. Hermes
2. OpenClaw

4. Dienste

Jeder laufende Hauptdienst bekommt eine eigene Markdown-Datei. Abhängigkeiten wie PostgreSQL, Redis, ClickHouse oder MinIO werden nicht als eigene Hauptseiten geführt, sondern innerhalb der Seite des zugehörigen Hauptdienstes erklärt.

Die Dienstseiten werden nach Kategorien sortiert.

Vereinbarte Kategorien und Reihenfolge:

1. Mail
2. KI
3. Infrastruktur

Innerhalb der Kategorien beginnt Mail mit Stalwart, danach Bulwark. Die weiteren Dienste folgen in einer nachvollziehbaren Reihenfolge.

5. Einheitliche Struktur pro Dienstseite

Jede Dienstseite soll ungefähr gleich aufgebaut sein:

1. Einleitung und Rolle des Dienstes
2. Was ist der Dienst?
3. Welche Rolle hat er in der Gesamtinfrastruktur?

4. Warum wird er betrieben?

5. Persistente Daten und Backup-Relevanz

6. Datenverzeichnisse
7. Datenbanken
8. Konfigurationsdateien
9. Env-Dateien und Secrets

10. Was muss für Restore/Backup erhalten bleiben?

11. Stack, Container und Docker Compose

12. Stack-Pfad
13. Container
14. Images
15. Ports und Bindings
16. Volumes

17. wichtige Compose-Besonderheiten

18. Zugehörige Dienste und Abhängigkeiten

19. Datenbanken
20. Caches
21. interne Storage-Dienste

22. andere Dienste, die angebunden sind

23. Kurzreferenz Secrets und Umgebungsvariablen

24. wichtige Env-Vars
25. Speicherort der Secrets
26. Hinweise, welche Werte nicht öffentlich dokumentiert werden

Der Zielumfang liegt grob bei ein bis zwei Seiten pro Hauptdienst, soweit der Dienst das hergibt.

6. Betriebsteil

Betriebsnahe Dateien wie Changelog und Aktualisierungsplan stehen am Ende der Navigation. Das Changelog bleibt append-only.

7. Legacy- und Planungsbereich

Alte Dokumente und nicht mehr aktive Planungsstände liegen unter .planning/.legacy/. Dieser Bereich ist ausdrücklich nicht die aktive Dokumentation und dient nur noch als Ablage für spätere Prüfung oder Rückverfolgung.