Docker Stacks¶

Diese Seite beschreibt die Docker-Compose-Konventionen der Selfhost-Infrastruktur. Sie erklärt nicht jede Anwendung im Detail; konkrete Dienstwerte stehen auf den Dienstseiten.

Grundprinzip¶

Docker-Dienste liegen unter:

/opt/selfhost/stacks/<stack-name>/

Ein Stack ist in der Regel ein Docker-Compose-Projekt. Ein Stack kann einen einzelnen Hauptdienst enthalten oder mehrere eng zusammengehörige Container, zum Beispiel Anwendung plus Datenbank.

Aktuelle Compose-Projekte¶

Projekt	Compose-Datei	Inhalt
`core`	`/opt/selfhost/stacks/core/docker-compose.yml`	Homepage, Portainer, Dozzle, Uptime Kuma, File Browser
`mail`	`/opt/selfhost/stacks/mail/docker-compose.yml`	Stalwart und Loopback-Proxy
`webmail`	`/opt/selfhost/stacks/webmail/docker-compose.yml`	Bulwark
`litellm`	`/opt/selfhost/stacks/litellm/docker-compose.yml`	LiteLLM und PostgreSQL
`openwebui`	`/opt/selfhost/stacks/openwebui/docker-compose.yml`	Open WebUI
`langfuse`	`/opt/selfhost/stacks/langfuse/docker-compose.yml`	Langfuse Web, Worker, PostgreSQL, Redis, ClickHouse, MinIO
`caddymanager`	`/opt/selfhost/stacks/caddymanager/docker-compose.yml`	CaddyManager Backend und Frontend

Port-Konvention¶

HTTP-Weboberflächen sollen auf dem Host nur an 127.0.0.1 binden. Caddy übernimmt die öffentliche Veröffentlichung per HTTPS.

Beispiele:

Dienst	Hostbindung
Homepage	`127.0.0.1:3000`
Uptime Kuma	`127.0.0.1:3001`
Open WebUI	`127.0.0.1:3020`
Langfuse	`127.0.0.1:3030`
LiteLLM	`127.0.0.1:4000`
CaddyManager Frontend	`127.0.0.1:8020`
File Browser	`127.0.0.1:8081`
Stalwart Admin/HTTP über Proxy	`127.0.0.1:8443`
Portainer	`127.0.0.1:9001`
Dozzle	`127.0.0.1:9999`

Bewusste Ausnahme: Mail-Protokolle von Stalwart binden öffentlich auf den notwendigen Standardports, unter anderem SMTP, Submission, IMAPS, POP3S und ManageSieve.

Container-Namen und Restart-Policy¶

Die Container verwenden sprechende Namen, zum Beispiel openwebui, litellm, langfuse-web oder stalwart. Dienste sollen mit:

restart: unless-stopped

betrieben werden, sofern es keinen guten Grund dagegen gibt.

Persistente Daten¶

Persistente Daten sollen unter /opt/selfhost/data/<dienst>/ oder als klar benannte Docker-Volumes liegen. Wenn Docker-Volumes verwendet werden, müssen sie auf der Dienstseite explizit dokumentiert werden, weil sie nicht sofort als normale Hostpfade sichtbar sind.

Beispiele:

Dienst	Persistenz
Portainer	`/opt/selfhost/data/portainer`
Uptime Kuma	`/opt/selfhost/data/uptime-kuma`
File Browser	`/opt/selfhost/data/filebrowser`
Open WebUI	`/opt/selfhost/data/openwebui`
LiteLLM	`/opt/selfhost/data/litellm/postgresql`, `/opt/selfhost/data/litellm/oauth-tokens`
Stalwart	`/opt/selfhost/data/stalwart/etc`, `/opt/selfhost/data/stalwart/data`
Bulwark	`/opt/selfhost/data/bulwark/settings`
Langfuse	Compose-Volumes `postgres_data`, `clickhouse_data`, `minio_data`
CaddyManager	`/opt/selfhost/data/caddymanager/sqlite`

Secrets und Env-Dateien¶

Secrets sollen nicht direkt in docker-compose.yml stehen. Für lokale Secret-Dateien gilt:

/opt/selfhost/secrets/<dienst>.env

Diese Dateien sollen root:selfhost gehören und nicht öffentlich lesbar sein. Die Details stehen unter Secrets und Backups.

Abhängigkeiten innerhalb eines Stacks¶

Dienste mit Datenbank oder Nebenkomponenten bleiben im selben Compose-Projekt, wenn sie eng gekoppelt sind. Beispiele:

LiteLLM mit eigener PostgreSQL-Datenbank.
Langfuse mit PostgreSQL, Redis, ClickHouse und MinIO.
Stalwart mit Loopback-Proxy für den lokalen Admin-/HTTPS-Zugriff.

Die Dienstseite des Hauptdienstes beschreibt diese Abhängigkeiten mit. Es gibt deshalb keine separaten Dienstseiten für jede interne Datenbank.

Container-zu-Host-Kommunikation¶

Wenn ein Container einen Dienst auf dem Host erreichen muss, soll nach Möglichkeit host.docker.internal verwendet werden:

extra_hosts:
  - "host.docker.internal:host-gateway"

Das vermeidet unnötige Wege über öffentliche Domains, DNS, TLS und Caddy, wenn die Kommunikation intern gemeint ist.

Lebenszyklusbefehle¶

Typische Befehle:

# Status aller Compose-Projekte
docker compose ls

# Stack prüfen
sudo docker compose -f /opt/selfhost/stacks/<stack>/docker-compose.yml config

# Stack starten oder aktualisieren
sudo docker compose -f /opt/selfhost/stacks/<stack>/docker-compose.yml up -d

# Stack stoppen
sudo docker compose -f /opt/selfhost/stacks/<stack>/docker-compose.yml down

# Logs ansehen
sudo docker logs <container>

Nach Änderungen an Webdiensten zusätzlich Registry/Caddy prüfen, falls Routen betroffen sind.

Was nicht in Stack-Verzeichnisse gehört¶

Nicht in aktive Stack-Verzeichnisse gehören:

alte Planungsnotizen
historische Authentik-Artefakte
ungenutzte Example-Dateien ohne aktiven Dienstbezug
generierte Dateien, die aus anderen Quellen reproduziert werden können

Solche Inhalte gehören entweder in die aktive Dokumentation, in /opt/selfhost/docs/.planning/ oder werden entfernt, wenn sie keinen Zweck mehr haben.