Zum Inhalt

Konzepte

Dieser Bereich beschreibt die Grundprinzipien der Selfhost-Infrastruktur. Die Konzeptseiten erklären nicht primär einzelne Anwendungen, sondern die Regeln und Zuständigkeiten, die für mehrere Dienste gelten.

Ziel der Konzeptseiten

Die Konzeptseiten sollen beantworten:

  • Wo liegt was auf dem Server?
  • Welche Komponente ist für Routing, TLS und Veröffentlichung zuständig?
  • Wie werden Docker-Stacks strukturiert?
  • Wo liegen persistente Daten, Konfigurationen und Secrets?
  • Welche Regeln gelten für Backups und Wiederherstellung?
  • Welche Ausnahmen gibt es, insbesondere beim Mail-Stack?

Abgrenzung zu Dienstseiten

Die Konzepte beschreiben das allgemeine Betriebsmodell. Dienstseiten beschreiben konkrete Anwendungen.

Beispiel CaddyManager:

  • Die Konzeptseite „Subdomain Registry und Caddy“ erklärt, dass routes.json die Quelle für Nicht-Mail-Routen ist, wie der Generator arbeitet und warum Caddy der öffentliche Einstiegspunkt ist.
  • Die Dienstseite „CaddyManager“ beschreibt die konkrete CaddyManager-Anwendung, ihren Docker-Stack, ihre Daten, Secrets und ihren Zugriff.

Damit bleibt die Dokumentation wartbar: Grundregeln werden einmal erklärt, konkrete Dienstwerte stehen auf den jeweiligen Dienstseiten.

Konzeptseiten

Seite Inhalt
Serverstruktur Verzeichnislayout, Systemdienste, Verantwortlichkeiten und Betriebsgrenzen
Subdomain Registry und Caddy routes.json, Generator, Caddy, Tailnet-Schutz und manuelle Mail-Ausnahmen
Docker Stacks Compose-Konventionen, Projektstruktur, Ports, Netzwerke und Lebenszyklus
Secrets und Backups Secret-Ablage, persistente Daten, Backup-Relevanz und Wiederherstellungsregeln

Leitprinzipien

  1. Caddy ist der zentrale öffentliche HTTP/S-Einstieg.
  2. Nicht-Mail-Routen werden aus der zentralen Subdomain Registry generiert.
  3. Mail-Routen bleiben bewusst manuell in Caddy gepflegt.
  4. Docker-Dienste binden HTTP-Ports nach Möglichkeit nur an 127.0.0.1.
  5. Jeder Hauptdienst hat eine eigene Dienstseite; Datenbanken und technische Abhängigkeiten werden dort mitbeschrieben.
  6. Secrets werden nicht in Compose-Dateien oder Dokumentationsseiten ausgeschrieben.
  7. Der Build der Dokumentation muss mit mkdocs build --strict erfolgreich sein.