Installation

Docker-Installation

FediSuite wird vollständig über Docker Compose betrieben. Du benötigst Docker, das Self-Hosting-Repository und eine .env-Datei mit deinen Einstellungen. Nichts wird lokal gebaut, das fertige Image kommt von Docker Hub.

1

Repository klonen

Klone das Self-Hosting-Repository auf deinen Server. Es enthält die docker-compose.yml, die .env.example und ein Beispiel für Traefik. Ohne Zielnamen im Befehl hieße der Ordner FediSuite-Self-Hosting, hier heißt er fedisuite.

bash
git clone https://forge.chrislo.de/FediSuite/FediSuite-Self-Hosting.git fedisuite
cd fedisuite
2

.env konfigurieren

Kopiere die Beispiel-Konfiguration und passe sie an. Alle Pflichtfelder müssen gesetzt sein, bevor du den Stack startest, insbesondere ADMIN_EMAIL und ADMIN_PASSWORD. Daraus legt FediSuite beim Start den ersten Admin-Account an.

bash
cp .env.example .env
nano .env

Pflichtfelder

FEDISUITE_IMAGE christinloehner/fedisuite:2.4.0

Docker-Image, das genutzt wird. Pflicht, und zwar mit einem festen Versions-Tag, zum Beispiel {{ $latestVersion }}. Der Tag latest wird vom Prüfskript abgelehnt. Auf ARM64-Servern gilt das Präfix arm64-, also arm64-{{ $latestVersion }}. Die Compose-Datei lädt Images nie von selbst, du holst sie mit docker compose pull --policy always.

APP_URL https://deine-domain.de

Vollständige öffentliche URL deiner FediSuite-Instanz inkl. https://, ohne abschließenden Schrägstrich.

JWT_SECRET (langer zufälliger String)

Geheimschlüssel für Login-Tokens. Verschlüsselt außerdem gespeicherte 2FA-Geheimnisse. Niemals weitergeben oder committen und nach dem Start nicht mehr ändern.

ACCOUNT_ENCRYPTION_KEY (64 Hex-Zeichen)

Eigener Schlüssel, der die Zugangsdaten verbundener Fediverse-Konten verschlüsselt (Tokens, Client-Secrets). Erzeuge ihn einmalig mit openssl rand -hex 32, nutze nicht den JWT_SECRET und sichere ihn getrennt vom Server. Ohne den Schlüssel startet FediSuite nicht, und geht er verloren, sind alle verbundenen Konten unbrauchbar.

POSTGRES_DB fedisuite

Name der PostgreSQL-Datenbank.

POSTGRES_USER fedisuite

Datenbankbenutzer.

POSTGRES_PASSWORD sicheres-passwort

Datenbankpasswort. Wähle ein langes, zufälliges Passwort.

POSTGRES_IMAGE postgres:18-alpine

PostgreSQL-Image der Datenbank. Neue Installationen verwenden PostgreSQL 18. Die Hauptversion später nicht einfach im Tag ändern: Für bestehende Installationen mit PostgreSQL 15 gibt es eine eigene Anleitung zum Wechsel.

POSTGRES_DATA_PATH ./postgres

Ordner auf dem Server, in dem PostgreSQL seine Daten speichert. Er wird beim ersten Start neben der docker-compose.yml angelegt. Niemals löschen: Er enthält alle Datenbankdaten.

POSTGRES_DATA_TARGET /var/lib/postgresql

Pfad im Container, in den der Ordner eingehängt wird. Für PostgreSQL 18 ist das /var/lib/postgresql (bei PostgreSQL 15 war es /var/lib/postgresql/data). Image und Pfad müssen zusammenpassen; das Prüfskript meldet Abweichungen.

DATABASE_URL postgresql://fedisuite:passwort@db:5432/fedisuite

Vollständige PostgreSQL-Verbindungszeichenfolge. Muss zu den POSTGRES_*-Werten passen.

ADMIN_EMAIL admin@deine-domain.de

E-Mail des ersten Admin-Accounts. Der Account wird beim Start angelegt, falls es ihn noch nicht gibt.

ADMIN_PASSWORD sicheres-admin-passwort

Passwort des ersten Admin-Accounts. Fehlt dieser Wert, wird kein Admin angelegt und ein Login ist nicht möglich.

SMTP_HOST smtp.dein-anbieter.de

SMTP-Server für ausgehende E-Mails.

SMTP_PORT 587

SMTP-Port (typischerweise 587 für STARTTLS oder 465 für SSL).

SMTP_USER dein-smtp-benutzer

Benutzername für die SMTP-Authentifizierung.

SMTP_PASS dein-smtp-passwort

Passwort für die SMTP-Authentifizierung.

SMTP_FROM no-reply@deine-domain.de

Absenderadresse für ausgehende E-Mails.

Optionale Felder

APP_NAME FediSuite

Name der Instanz, z.B. in E-Mails.

PUBLIC_SITE_URL https://deine-domain.de

Öffentliche URL der Instanz für den Standard-User-Agent und die Instanzliste, falls abweichend von APP_URL.

OUTBOUND_HTTP_USER_AGENT Mozilla/5.0 (compatible; …)

User-Agent-Header für ausgehende HTTP-Anfragen an Fediverse-Instanzen. Standard: Mozilla/5.0 (compatible; APP_NAME/1.0; +PUBLIC_SITE_URL).

ENABLE_USER_REGISTRATION true

Auf false setzen, um neue Registrierungen zu sperren. Der Admin aus ADMIN_EMAIL wird trotzdem angelegt.

TRUST_PROXY 0

Wie vielen Reverse-Proxy-Stationen FediSuite bei der Client-IP vertraut. 0 bei direktem Zugriff auf Port 3000 (Vorlage), 1 hinter genau einem Proxy wie Traefik. Falsch gesetzt können Clients IP-Adressen fälschen, die für Rate Limits und Audit-Logs genutzt werden.

Wichtig: Bei jedem Start der app prüft FediSuite, ob es einen Benutzer mit der Adresse aus ADMIN_EMAIL gibt. Falls nicht, wird er mit ADMIN_PASSWORD angelegt, andernfalls bleibt das Passwort unverändert. Ein späteres Ändern von ADMIN_PASSWORD in der .env setzt das Passwort also nicht zurück. Fehlt ADMIN_PASSWORD, wird kein Admin angelegt.
SMTP ist Pflicht: FediSuite versendet E-Mails für die Registrierung, den Passwort-Reset und Abläufe rund um den historischen Import nach dem Verbinden von Fediverse-Konten. Lass die SMTP-Einstellungen nicht leer. Ohne Konfiguration versucht FediSuite, einen SMTP-Server auf localhost:1025 zu erreichen.
3

Stack starten

Verzeichnisrechte: Das Image läuft ohne Root-Rechte als UID/GID 1000. Die gemounteten Ordner uploads, plugins und logs müssen für diesen Benutzer beschreibbar sein. Lege sie deshalb vor dem ersten Start so an:
bash
install -d -m 0750 -o 1000 -g 1000 uploads plugins logs

Nutze bei einem Berechtigungsfehler nicht Root als Workaround, sondern passe den Besitzer der Ordner an.

Prüfe zuerst die Konfiguration, hole dann die Images und starte alle Container im Hintergrund. Die Images lädt die Compose-Datei nie von selbst (pull_policy: never), deshalb ist der Pull-Schritt nötig. Die Datenbank-Initialisierung läuft beim Start automatisch ab, separate Migrations-Befehle sind nicht nötig.

bash
./scripts/check-config.sh
docker compose pull --policy always
docker compose up -d

Der Stack besteht aus vier Services:

db postgres:18-alpine

PostgreSQL-Datenbank

app christinloehner/fedisuite:2.4.0

Web-Oberfläche und API. Initialisiert beim Start die Datenbank und meldet über /api/health, ob die App bereit ist

worker1 christinloehner/fedisuite:2.4.0

Hintergrundjobs: Scheduler für geplante Beiträge, Aktualisierung der Beitragszahlen, Reichweiten, Erinnerungen, Tipps

worker2 christinloehner/fedisuite:2.4.0

Hintergrundjobs: Aktualisierung der Beitragszahlen, Reichweiten, Tipps

Die App lauscht auf Port 3000, den die Compose-Datei auf dem Host veröffentlicht. Über Traefik-Labels in der docker-compose.yml kannst du sie unter deiner Domain erreichbar machen, die Labels sind bereits als Kommentar vorbereitet (siehe Reverse Proxy). Die Worker starten erst, wenn der Healthcheck der app bestanden ist. Wie lange das dauert, steht auf der Seite Konfiguration.

4

Erster Login

Sobald db und app den Status healthy haben, ist die App erreichbar. Öffne deine Domain (APP_URL) im Browser und melde dich mit den in der .env gesetzten Admin-Zugangsdaten an.

FediSuite läuft unter
https://deine-domain.de

Login

Wert aus ADMIN_EMAIL

Passwort

Wert aus ADMIN_PASSWORD
Tipp: Nach docker compose up -d startet zuerst db. Sobald der Healthcheck besteht, startet app und initialisiert die Datenbank. Die Worker folgen, wenn app healthy ist. Du kannst den Fortschritt mit docker compose logs -f app verfolgen. Nach dem ersten Login empfiehlt sich, in den Einstellungen die Zwei-Faktor-Authentifizierung für den Admin-Account einzurichten.

Status & nützliche Befehle

Status aller Container prüfen

Zeigt alle laufenden Container und ihren Health-Status.

docker compose ps

Logs in Echtzeit verfolgen

Zeigt laufende Log-Ausgaben aller oder einzelner Container.

docker compose logs -f
docker compose logs -f app      # nur App
docker compose logs -f worker1  # nur Worker 1

Update auf neuere Version

Sichert die Instanz, holt das neue Image und startet betroffene Container neu. Vorher die Compose-Datei per git pull aktualisieren und den Tag in der .env anpassen, siehe Seite Updates.

docker compose stop app worker1 worker2
./scripts/backup.sh /pfad/zum/backup-speicher
docker compose pull --policy always
docker compose up -d

Backup erstellen

Sichert Datenbank, .env, Uploads und Plugins in ein Archiv. Das Archiv enthält Passwörter und den ACCOUNT_ENCRYPTION_KEY, behandle es wie ein Geheimnis. Mehr unter Backup & Restore.

docker compose stop app worker1 worker2
./scripts/backup.sh /pfad/zum/backup-speicher
docker compose start app worker1 worker2

Health-Endpunkt der App prüfen

Liefert JSON mit status und db, sobald die App läuft und die Datenbank erreichbar ist. Die Compose-Datei nutzt denselben Endpunkt für den Healthcheck.

curl -s http://127.0.0.1:3000/api/health

Konfiguration vor dem Start prüfen

Prüft die .env und die Compose-Datei (fester Versions-Tag, PostgreSQL-Image und passender Mount-Pfad) und gibt keine Geheimnisse aus. Gib docker compose config nicht ohne --quiet aus und poste es nirgends: Die Ausgabe enthält die Werte aus deiner .env.

./scripts/check-config.sh

Stack neu starten

Startet alle Container neu, ohne sie neu zu erstellen. Geänderte .env-Werte werden dabei nicht neu eingelesen. Dafür ist docker compose up -d nötig.

docker compose restart