Serverstruktur¶
Diese Seite beschreibt die Grundstruktur des VPS und die wichtigsten Verantwortlichkeiten der Verzeichnisse und Systemdienste. Sie ist bewusst dienstübergreifend gehalten. Details einzelner Anwendungen stehen in den jeweiligen Dienstseiten.
Rolle des Servers¶
Der VPS ist der zentrale Selfhost-Host für öffentliche Webseiten, Mail, KI-Dienste, Administrationsoberflächen und Agenten. Die Infrastruktur ist so aufgebaut, dass möglichst viel explizit unter /opt/selfhost liegt und dadurch auffindbar, dokumentierbar und sicherbar bleibt.
Der Server betreibt drei Arten von Komponenten:
- Systemdienste des Hosts, zum Beispiel Caddy, Docker, Tailscale, Fail2Ban und Cockpit.
- Docker-Compose-Stacks unter
/opt/selfhost/stacks/. - Nativ laufende Agenten oder Tools, insbesondere Hermes und OpenClaw, soweit sie nicht als Docker-Stack betrieben werden.
Wichtige Basispfade¶
| Pfad | Zweck | Bearbeitung |
|---|---|---|
/opt/selfhost/ |
Wurzel der Selfhost-Infrastruktur | zentrale Arbeitsbasis |
/opt/selfhost/registry/routes.json |
Quelle für Nicht-Mail-Routen | von Hand editieren, danach Generator ausführen |
/opt/selfhost/generated/ |
generierte Artefakte | nicht manuell bearbeiten |
/opt/selfhost/generated/caddy/routes.caddy |
generierte Caddy-Routen | nur über Registry/Generator ändern |
/opt/selfhost/generated/homepage/services.yaml |
generierte Homepage-Liste | nur über Registry/Generator ändern |
/opt/selfhost/generated/routes/ |
statische Subdomain-Registry-Übersicht | nur über Generator ändern |
/opt/selfhost/generated/openclaw-error/ |
Hinweis-/Fallbackseite für nicht berechtigte Tailnet-Zugriffe | bewusst wiederverwendet |
/opt/selfhost/stacks/ |
Docker-Compose-Stacks | je Dienst/Stack ein Unterordner |
/opt/selfhost/data/ |
persistente Dienst- und Anwendungsdaten | backuprelevant |
/opt/selfhost/secrets/ |
lokale .env-Dateien und Übergangs-Secrets |
niemals öffentlich dokumentieren |
/opt/selfhost/docs/ |
MkDocs-Markdown-Quellen | aktiv gepflegte Dokumentation |
/opt/selfhost/site/ |
gebautes MkDocs-HTML | Build-Artefakt, nicht manuell ändern |
/opt/selfhost/tools/ |
Hilfsprogramme, Generatoren und virtuelle Umgebungen | kontrolliert ändern |
/opt/selfhost/backups/ |
lokale Backup-Ablage | nicht als einzige Backup-Quelle betrachten |
Generierte Dateien¶
Alles unter /opt/selfhost/generated/ ist grundsätzlich als erzeugtes Artefakt zu behandeln. Änderungen an diesen Dateien gehen beim nächsten Generatorlauf verloren.
Der wichtigste Generator ist:
/opt/selfhost/tools/selfhost-routes
Er erzeugt aus /opt/selfhost/registry/routes.json unter anderem:
- Caddy-Routen unter
/opt/selfhost/generated/caddy/routes.caddy - Homepage-/Dashboard-Einträge
- Subdomain-Übersichten
- eine statische HTML-Übersicht unter
/opt/selfhost/generated/routes/
Aktive Systemdienste¶
| Dienst | Rolle |
|---|---|
caddy |
Reverse Proxy, TLS-Terminierung und statische Auslieferung |
docker |
Container-Laufzeitumgebung für Compose-Stacks |
tailscaled |
Tailnet-Anbindung und IP-basierter Zugriffsschutz für ausgewählte Seiten |
fail2ban |
Basisschutz gegen wiederholte Fehlversuche und Scans |
cockpit.socket |
Host-Verwaltung über Cockpit |
selfhost-config-backup.timer |
täglicher lokaler Konfigurationsbackup-Lauf |
Caddy ist für HTTP/S der zentrale Einstiegspunkt. Dienste sollen ihre Webports nicht direkt öffentlich veröffentlichen, sondern nur lokal binden und über Caddy erreichbar sein. Eine bewusste Ausnahme sind Mail-Protokollports wie SMTP, Submission, IMAPS, POP3S und ManageSieve, die direkt von Stalwart angeboten werden müssen.
Docker-Compose-Projekte¶
Aktuell werden die Hauptdienste über mehrere Compose-Projekte betrieben:
| Compose-Projekt | Hauptinhalt |
|---|---|
core |
Homepage, Portainer, Dozzle, Uptime Kuma, File Browser |
mail |
Stalwart und Loopback-Proxy |
webmail |
Bulwark |
litellm |
LiteLLM und PostgreSQL |
openwebui |
Open WebUI |
langfuse |
Langfuse Web, Worker, PostgreSQL, Redis, ClickHouse, MinIO |
caddymanager |
CaddyManager Frontend und Backend |
Die genaue Docker-Struktur wird auf der Konzeptseite Docker Stacks beschrieben. Konkrete Images, Ports und Datenpfade stehen auf den Dienstseiten.
Agenten¶
Hermes und OpenClaw gehören zur Infrastruktur und werden deshalb in einem eigenen Bereich dokumentiert. Sie sind keine klassischen Dienstseiten, weil sie als Agenten teilweise mit Tools, Konfiguration, API-Endpunkten, Dashboards und externer Nutzung zusammenhängen.
Siehe:
Dokumentation als Teil der Infrastruktur¶
Die Dokumentation selbst ist ebenfalls ein betriebener Bestandteil:
- Quellen:
/opt/selfhost/docs/ - MkDocs-Konfiguration:
/opt/selfhost/mkdocs.yml - Build-Ausgabe:
/opt/selfhost/site/ - veröffentlichte Route:
serverdocs.marcosudau.com
Der Buildvorgang ist unter Dokumentation bauen und veröffentlichen beschrieben.
Legacy- und Planungsbereich¶
Das Verzeichnis /opt/selfhost/docs/.planning/ ist ein bewusst entschärfter Arbeitsbereich für Notizen, temporäre Planungen und alte Artefakte. Inhalte dort gelten nicht automatisch als aktueller Dokumentationsstand.
Alte Authentik-Dokumente und Rückbauartefakte liegen unter:
/opt/selfhost/docs/.planning/.legacy/
Aktive Dokumentation liegt dagegen direkt unter /opt/selfhost/docs/ und ist in mkdocs.yml eingetragen.