Installation

Konfiguration

Die Datei docker-compose.yml steuert, welche Container FediSuite startet, wie sie miteinander reden, wo Daten gespeichert werden und was passiert, wenn ein Container abstürzt. Diese Seite erklärt die mitgelieferte Datei Service für Service.

Was ist die docker-compose.yml?

Die docker-compose.yml beschreibt, welche Container gestartet werden, wie sie sich gegenseitig erreichen, wo sie ihre Daten ablegen und in welcher Reihenfolge sie starten. Docker Compose liest die Datei und setzt den Stack um, ein Container ist dabei ein Programm in einer isolierten Umgebung mit eigenem Dateisystem und eigenem Netzwerk.

Für einen einfachen Betrieb musst du die docker-compose.yml nicht anfassen. Domain, Passwörter und E-Mail-Konfiguration gehören in die .env-Datei. Anpassen musst du die Compose-Datei nur, wenn du die Worker verändern oder einen Reverse Proxy einbinden willst.

Eigene Änderungen am besten in eine docker-compose.override.yml auslagern. Docker Compose lädt sie automatisch zusätzlich, und das Self-Hosting-Repository führt sie in der .gitignore. So bleibt die mitgelieferte Datei unverändert und lässt sich mit git pull aktualisieren.

Überblick: die vier Services

Die mitgelieferte Compose-Datei startet vier Container. Jeder hat eine klar abgegrenzte Aufgabe:

db postgres:18-alpine
Pflicht

Die Datenbank. Speichert Nutzer*innen, Beiträge, Entwürfe, Konto-Verknüpfungen, Einstellungen und Verlaufsdaten dauerhaft.

app christinloehner/fedisuite:2.4.0
Pflicht

Stellt die Web-Oberfläche und die API bereit. Führt bei jedem Start zuerst node server/init-db.js aus (Schema, Migrationen, Admin-Account) und startet danach den Server.

worker1 christinloehner/fedisuite:2.4.0
Optional

Hintergrundjobs: veröffentlicht geplante Beiträge (Scheduler), aktualisiert Beitragszahlen und Reichweiten, versendet die Erinnerung an Nutzer*innen ohne verbundenes Konto und erzeugt Tipps. Als einziger Container mit aktivem Scheduler.

worker2 christinloehner/fedisuite:2.4.0
Optional

Zusätzlicher Worker: aktualisiert Beitragszahlen und erzeugt Tipps. Scheduler und Erinnerung sind hier abgeschaltet. Weitere Worker kannst du als Kopie dieses Blocks ergänzen.

Wichtig: FediSuite braucht weder Redis noch einen anderen Queue- oder Cache-Dienst. Die Hintergrundjobs laufen als Timer in den Node.js-Prozessen, die Warteschlange für die Reichweiten-Berechnung liegt in der PostgreSQL-Datenbank.

Service: db (PostgreSQL)

docker-compose.yml
  db:
    image: ${POSTGRES_IMAGE:?Set POSTGRES_IMAGE in .env before starting the stack}
    pull_policy: never
    env_file:
      - .env
    restart: unless-stopped
    stop_grace_period: 1m
    volumes:
      - "${POSTGRES_DATA_PATH:?Set POSTGRES_DATA_PATH in .env}:${POSTGRES_DATA_TARGET:?Set POSTGRES_DATA_TARGET in .env}"
    healthcheck:
      test: ["CMD-SHELL", "pg_isready -U $${POSTGRES_USER} -d $${POSTGRES_DB}"]
      interval: 5s
      timeout: 5s
      retries: 5
      start_period: 30s
    logging: *default-logging

image: ${POSTGRES_IMAGE}

Das PostgreSQL-Image steht nicht mehr fest in der Datei, sondern kommt aus POSTGRES_IMAGE in deiner .env. Neue Installationen verwenden postgres:18-alpine, das offizielle PostgreSQL-Image in Version 18 auf Basis von Alpine Linux. FediSuite nutzt PostgreSQL; MySQL oder andere Datenbanken werden nicht unterstützt. Das Datenverzeichnis ist zwischen PostgreSQL-Hauptversionen nicht kompatibel: Bei einer bestehenden Installation mit PostgreSQL 15 änderst du den Tag deshalb nicht einfach, sondern folgst der Anleitung PostgreSQL 15 auf 18 aktualisieren. Das ? in der Variable bedeutet: Fehlt der Wert, bricht Docker Compose mit der angegebenen Meldung ab, statt still etwas Falsches zu starten. pull_policy: never heißt, dass Docker das Image nie von selbst herunterlädt; du holst es mit docker compose pull --policy always (siehe Updates).

env_file: .env

Der Datenbankcontainer liest POSTGRES_DB, POSTGRES_USER und POSTGRES_PASSWORD aus deiner .env. Der Benutzer ist zugleich Superuser der Datenbank. Die Werte werden nur beim ersten Anlegen des Datenverzeichnisses ausgewertet: Ein späteres Ändern von POSTGRES_PASSWORD in der .env ändert das Passwort in einer bestehenden Datenbank nicht.

restart: unless-stopped

Stürzt der Container ab oder startet der Server neu, fährt Docker ihn wieder hoch, außer du hast ihn bewusst mit docker compose stop angehalten.

stop_grace_period: 1m

Beim Stoppen gibt Docker PostgreSQL bis zu eine Minute Zeit, um sauber herunterzufahren und alle Daten auf die Platte zu schreiben. Der Docker-Standard sind nur zehn Sekunden. Wird PostgreSQL vorher hart beendet, muss es beim nächsten Start einen Absturz reparieren (Crash-Recovery), was den Start verzögert.

volumes: ${POSTGRES_DATA_PATH}:${POSTGRES_DATA_TARGET}

Der Ordner POSTGRES_DATA_PATH auf deinem Server wird mit dem Datenverzeichnis innerhalb des Containers verknüpft (Bind Mount). Die Werte kommen aus deiner .env. Bei einer neuen Installation sind das POSTGRES_DATA_PATH=./postgres und POSTGRES_DATA_TARGET=/var/lib/postgresql. Das Ziel im Container hängt von der PostgreSQL-Version ab: PostgreSQL 18 braucht /var/lib/postgresql, PostgreSQL 15 braucht /var/lib/postgresql/data. Ohne dieses Volume wären alle Daten weg, sobald der Container neu erstellt wird, zum Beispiel bei einem Update.

Merke: Das Verzeichnis ./postgres/ entsteht beim ersten Start neben der docker-compose.yml. Lösche es niemals, es enthält alle deine Daten. Die .gitignore des Repositories führt es auf, du committest es also nicht versehentlich. Der Ordner gehört dem Datenbank-Benutzer des Containers; zum Ansehen oder Messen brauchst du auf dem Host sudo.

healthcheck

Docker ruft alle 5 Sekunden pg_isready auf. Während der ersten 30 Sekunden (start_period) zählen Fehlversuche nicht, damit eine langsam startende Datenbank nicht sofort als defekt gilt. Schlägt der Check danach fünfmal hintereinander fehl, gilt der Container als unhealthy. Die App und die Worker starten erst, wenn die Datenbank healthy meldet, damit sie nicht auf eine Datenbank zugreifen, die noch hochfährt.

logging: *default-logging

Docker begrenzt die Container-Logs auf fünf Dateien mit je 25 MB und überschreibt danach die ältesten. Ohne diese Begrenzung wachsen die Logs unbegrenzt und können mit der Zeit die Festplatte füllen. Der Block *default-logging steht einmal am Dateianfang und wird von allen Diensten verwendet (siehe „Gemeinsame Blöcke“ unten).

Service: app

docker-compose.yml
  app:
    image: ${FEDISUITE_IMAGE:?Set FEDISUITE_IMAGE to an explicit version in .env}
    pull_policy: never
    env_file:
      - .env
    environment:
      - ENABLE_SCHEDULER=false
      - ENABLE_POSTS_REFRESH=false
      - ENABLE_IDLE_REMINDER=false
      - ENABLE_TIPS_ENGINE=false
      - ENABLE_REACH_REFRESH=false
      - PLUGINS_ENABLED=${PLUGINS_ENABLED:-true}
      - PLUGIN_SCAN_ON_START=${PLUGIN_SCAN_ON_START:-true}
      - PLUGIN_API_VERSION=${PLUGIN_API_VERSION:-1}
    depends_on:
      db:
        condition: service_healthy
    volumes:
      - ./uploads:/app/uploads
      - ./plugins:/app/plugins
      - ./logs:/app/logs
    ports:
      - "3000:3000"
    restart: unless-stopped
    command: sh -c "node server/init-db.js && node server/index.js"
    healthcheck: *fedisuite-healthcheck
    logging: *default-logging

image: ${FEDISUITE_IMAGE}

Nutzt das Image aus FEDISUITE_IMAGE in deiner .env. Die Variable ist Pflicht und muss einen festen Versions-Tag enthalten, zum Beispiel christinloehner/fedisuite:2.4.0. latest ist nicht vorgesehen; das mitgelieferte Prüfskript scripts/check-config.sh lehnt es ab. Die verfügbaren Tags stehen auf der Seite Umgebungsvariablen.

pull_policy: never

Docker lädt Images nie von selbst herunter, auch nicht bei docker compose up -d. Ein Update passiert deshalb nur, wenn du es bewusst auslöst: Du änderst den Tag in der .env und holst das Image mit docker compose pull --policy always. Eine Konfigurationsänderung kann so nie versehentlich auf eine neue Version aktualisieren. Wurde das Image noch nicht heruntergeladen, meldet docker compose up, dass es nicht vorhanden ist; hole es dann mit dem Pull-Befehl.

environment: ENABLE_*=false

Der app-Container hat in der Standardkonfiguration Scheduler, Beitrags-Refresh, Reichweiten-Refresh, Erinnerung und Tipps abgeschaltet, das übernehmen die Worker. Was in environment steht, überschreibt gleichnamige Werte aus der .env (die per env_file geladen wird). Die Variablen in der .env gelten deshalb für den app-Container nur, wenn sie nicht in environment stehen. Der Wiederholungs-Worker für historische Importe läuft in jedem Container, auch in app.

PLUGINS_ENABLED, PLUGIN_SCAN_ON_START, PLUGIN_API_VERSION

Steuern das Plugin-System. PLUGINS_ENABLED=true schaltet es ein, PLUGIN_SCAN_ON_START=true durchsucht beim Start den Ordner /app/plugins nach Plugins (Ordner mit einer plugin.json), PLUGIN_API_VERSION ist die Plugin-API-Version der Instanz (aktuell 1). Details auf den Seiten zu Plugins.

depends_on: db: condition: service_healthy

Die App wartet, bis der db-Container seinen Healthcheck besteht. Ohne diese Abhängigkeit könnte sie beim ersten Start versuchen, die Datenbank zu initialisieren, bevor PostgreSQL bereit ist.

ports: "3000:3000"

Die App lauscht im Container auf Port 3000. Das Mapping 3000:3000 veröffentlicht ihn auf dem Host, und zwar auf allen Schnittstellen. Docker umgeht dabei Firewalls wie ufw. Mit Reverse Proxy solltest du das Mapping entfernen oder auf 127.0.0.1:3000:3000 beschränken (siehe Reverse Proxy).

volumes: ./uploads, ./plugins & ./logs

Drei Bind Mounts, die App und Worker gemeinsam nutzen:

  • •./uploads:/app/uploads: Anhänge zu Beiträgen und Entwürfen. Seit FediSuite 2.0 bleiben die Dateien eines Beitrags auch nach der Veröffentlichung erhalten, damit er als Entwurf wiederverwendet werden kann. Sie werden gelöscht, wenn der Beitrag gelöscht wird.
  • •./plugins:/app/plugins: der Plugins-Ordner. Plugins werden auf dem Host abgelegt und sind für App und Worker sichtbar.
  • •./logs:/app/logs: Audit-Logs. FediSuite schreibt sicherheitsrelevante Ereignisse (Login, Registrierung, Zwei-Faktor-Authentifizierung u. a.) als JSON-Zeilen in monatlich wechselnde Dateien (audit-YYYY-MM.log, Monat in UTC). E-Mail-Adressen und Fediverse-Handles werden darin teilweise maskiert. Die Logs erscheinen nicht in der Container-Ausgabe.

healthcheck

Alle 10 Sekunden fragt Docker http://127.0.0.1:3000/api/health ab. Die Antwort enthält den Zustand der Datenbankverbindung. start_period: 10m bedeutet: In den ersten zehn Minuten nach dem Start zählen Fehlversuche nicht, damit lange Datenbankmigrationen den Container nicht als defekt markieren. Sobald ein Check besteht, ist der Container healthy. Danach führen fünf aufeinanderfolgende Fehlschläge zu unhealthy. Die Worker warten auf diesen Zustand (siehe unten). Die Definition steht einmal als gemeinsamer Block am Dateianfang und gilt für app, worker1 und worker2.

command: node server/init-db.js && node server/index.js

Beim Start laufen zwei Schritte nacheinander: init-db.js legt das Datenbankschema an oder bringt es auf den aktuellen Stand und legt den Admin-Account aus ADMIN_EMAIL und ADMIN_PASSWORD an, falls es ihn noch nicht gibt. Schlägt ein Schritt fehl, startet der Server nicht. Danach startet index.js die eigentliche App. Du musst nichts manuell anstoßen.

Worker: Hintergrundaufgaben

Der app-Container nimmt Anfragen von Nutzer*innen entgegen und beantwortet sie sofort. Die Worker erledigen alles, was nicht sofort passieren muss, aber regelmäßig laufen muss. Sie nutzen dasselbe Image wie die App und starten node server/index.js, veröffentlichen aber keinen Port und haben andere Umgebungsvariablen.

Diese Aufgaben laufen automatisch im Hintergrund:

Geplante Beiträge veröffentlichen

Der Scheduler prüft jede Minute, ob Beiträge fällig sind, und veröffentlicht sie auf der jeweiligen Plattform. Er gibt außerdem Beiträge frei, die mitten in der Veröffentlichung hängen geblieben sind (nach 30 Minuten ohne Änderung).

Beitragszahlen aktualisieren

Jede Minute werden fällige Konten abgearbeitet: neue Beiträge, Likes, Boosts, Antworten und Benachrichtigungen. Pro Stunde liest eine Rotation außerdem einige ältere Beiträge neu ein, damit ihre Zähler aktuell bleiben.

Reichweite berechnen

Eine Warteschlange in der Datenbank sammelt Aufträge zur Reichweiten-Berechnung. Jeder Prozess arbeitet sie in kleinen Stapeln ab und begrenzt die gleichzeitigen Anfragen pro fremder Instanz. Dieser Worker läuft in der Standarddatei in beiden Workern, nicht im app-Container.

Erinnerung senden

Einmal pro Nutzer*in: Wer sich vor mehr als 48 Stunden registriert und bestätigt, aber noch kein Fediverse-Konto verbunden hat, bekommt eine E-Mail. Das Admin-Konto aus der .env ist ausgenommen.

Tipps erzeugen

Alle sechs Stunden werden die gespeicherten Tipps aller verbundenen Konten neu berechnet, etwa zu Posting-Zeiten und Formaten.

Instanzliste abgleichen

Ist die Instanz im Verzeichnis unter fedisuite.com/instances veröffentlicht, gleicht der Container mit aktivem Scheduler die Angaben (Name, Version, Nutzerzahl) alle zwei Stunden ab.

Was passiert ohne Worker? Läuft kein Worker und übernimmt der app-Container die Jobs nicht selbst, werden geplante Beiträge nicht veröffentlicht, Beitragszahlen bleiben eingefroren und Erinnerungen und Tipps werden nicht erzeugt. Entweder betreibst du mindestens einen Worker, oder du schaltest die Jobs im app-Container ein (Minimalbetrieb, siehe unten).

Wie viele Worker?

Eine feste Formel gibt es nicht. Die Compose-Datei startet zwei Worker, das ist der Ausgangspunkt:

Nur du selbst oder eine sehr kleine Gruppe

Kein Worker

Die Jobs laufen direkt im app-Container (Minimalbetrieb). Das spart Container und Arbeitsspeicher.

Standard

2 Worker

Wie mitgeliefert. worker1 hat den Scheduler und die Erinnerung, worker2 hilft bei Beitragszahlen und Tipps. Der app-Container bleibt für die Web-Oberfläche frei.

Viele Konten oder lange Warteschlange

weitere Worker

Zusätzliche Worker verteilen die Aktualisierung von Konten und die Reichweiten-Warteschlange. Die Arbeit wird über die Datenbank aufgeteilt, die Worker laufen deshalb gefahrlos parallel. Ob mehr Worker helfen oder eher REFRESH_BATCH_SIZE und die REACH_*-Werte, siehst du in den Logs.

Konfiguration der Worker

Alle Worker nutzen dasselbe Image wie app, aber ohne veröffentlichten Port. Die Aufgabenverteilung steuern Umgebungsvariablen. Der Scheduler gehört in genau einen Container (ENABLE_SCHEDULER=true nur in worker1). Jeder Beitrag wird vor der Veröffentlichung atomar beansprucht, ein zweiter Scheduler würde ihn daher nicht doppelt posten, wäre aber überflüssig.

docker-compose.yml: worker1 (der Hauptworker)
  worker1:
    image: ${FEDISUITE_IMAGE:?Set FEDISUITE_IMAGE to an explicit version in .env}
    pull_policy: never
    env_file:
      - .env
    environment:
      - ENABLE_SCHEDULER=true   # nur hier true: veröffentlicht geplante Beiträge
      - ENABLE_POSTS_REFRESH=true   # Konten aktualisieren
      - ENABLE_IDLE_REMINDER=true   # Erinnerungs-E-Mails
      - ENABLE_TIPS_ENGINE=true   # Tipps erzeugen
      - ENABLE_REACH_REFRESH=true
      - WORKER_ID=worker-1
      - REFRESH_BATCH_SIZE=${REFRESH_BATCH_SIZE:-5}
      - PLUGINS_ENABLED=${PLUGINS_ENABLED:-true}
      - PLUGIN_SCAN_ON_START=${PLUGIN_SCAN_ON_START:-true}
      - PLUGIN_API_VERSION=${PLUGIN_API_VERSION:-1}
    depends_on:
      db:
        condition: service_healthy
      app:
        condition: service_healthy
    restart: unless-stopped
    volumes:
      - ./uploads:/app/uploads
      - ./plugins:/app/plugins
      - ./logs:/app/logs
    command: sh -c "node server/index.js"
    healthcheck: *fedisuite-healthcheck
    logging: *default-logging
docker-compose.yml: worker2 (zusätzlicher Worker)
  worker2:
    image: ${FEDISUITE_IMAGE:?Set FEDISUITE_IMAGE to an explicit version in .env}
    pull_policy: never
    env_file:
      - .env
    environment:
      - ENABLE_SCHEDULER=false   # false: der Scheduler läuft nur in worker1
      - ENABLE_POSTS_REFRESH=true   # hilft bei der Aktualisierung
      - ENABLE_IDLE_REMINDER=false   # ein Container reicht
      - ENABLE_TIPS_ENGINE=true   # Tipps parallel verarbeiten
      - ENABLE_REACH_REFRESH=true
      - WORKER_ID=worker-2
      - REFRESH_BATCH_SIZE=${REFRESH_BATCH_SIZE:-5}
      - PLUGINS_ENABLED=${PLUGINS_ENABLED:-true}
      - PLUGIN_SCAN_ON_START=${PLUGIN_SCAN_ON_START:-true}
      - PLUGIN_API_VERSION=${PLUGIN_API_VERSION:-1}
    depends_on:
      db:
        condition: service_healthy
      app:
        condition: service_healthy
    restart: unless-stopped
    volumes:
      - ./uploads:/app/uploads
      - ./plugins:/app/plugins
      - ./logs:/app/logs
    command: sh -c "node server/index.js"
    healthcheck: *fedisuite-healthcheck
    logging: *default-logging

Weitere Worker hinzufügen (worker3, worker4 …)

Kopiere den worker2-Block und erhöhe die Nummer im Service-Namen und in WORKER_ID. Alle weiteren Worker haben ENABLE_SCHEDULER=false und ENABLE_IDLE_REMINDER=false. Die WORKER_ID muss pro Worker eindeutig sein.

  worker3:
    image: ${FEDISUITE_IMAGE:?Set FEDISUITE_IMAGE to an explicit version in .env}
    pull_policy: never
    env_file:
      - .env
    environment:
      - ENABLE_SCHEDULER=false
      - ENABLE_POSTS_REFRESH=true
      - ENABLE_IDLE_REMINDER=false
      - ENABLE_TIPS_ENGINE=true
      - ENABLE_REACH_REFRESH=true
      - WORKER_ID=worker-3
      - REFRESH_BATCH_SIZE=${REFRESH_BATCH_SIZE:-5}
      - PLUGINS_ENABLED=${PLUGINS_ENABLED:-true}
      - PLUGIN_SCAN_ON_START=${PLUGIN_SCAN_ON_START:-true}
      - PLUGIN_API_VERSION=${PLUGIN_API_VERSION:-1}
    depends_on:
      db:
        condition: service_healthy
      app:
        condition: service_healthy
    restart: unless-stopped
    volumes:
      - ./uploads:/app/uploads
      - ./plugins:/app/plugins
      - ./logs:/app/logs
    command: sh -c "node server/index.js"
    healthcheck: *fedisuite-healthcheck
    logging: *default-logging

Was bedeuten die Variablen im Detail?

ENABLE_SCHEDULER

Steuert, ob der Container fällige geplante Beiträge veröffentlicht (jede Minute) und, falls die Instanz im Verzeichnis veröffentlicht ist, die Instanzliste abgleicht. Standard im Code: true, die Compose-Datei setzt es in worker1 auf true und sonst auf false.

ENABLE_POSTS_REFRESH

Aktualisiert regelmäßig Konten und Beitragszahlen (jede Minute ein Stapel). Darf in mehreren Containern laufen, die Konten werden per Datenbanksperre aufgeteilt. Standard: true.

ENABLE_REACH_REFRESH

Schaltet die Reichweiten-Warteschlange ein. In der Compose-Datei ist sie in worker1 und worker2 auf true und in app auf false gesetzt. Standard im Code: true.

ENABLE_IDLE_REMINDER

Versendet die einmalige Erinnerung an Nutzer*innen ohne verbundenes Fediverse-Konto (stündliche Prüfung, höchstens 50 pro Durchlauf). Ein Container genügt. Standard: true.

ENABLE_TIPS_ENGINE

Erzeugt alle sechs Stunden die Tipps. Darf in mehreren Containern laufen. Standard: true.

WORKER_ID

Frei wählbarer, eindeutiger Name des Containers, zum Beispiel worker-1. Er erscheint in den Logs und in Sperren und Warteschlangen. Ohne Angabe nutzt FediSuite den Hostnamen des Containers.

REFRESH_BATCH_SIZE

Wie viele Konten ein Worker pro Durchlauf (alle 60 Sekunden) aktualisiert. Wertebereich 1 bis 50, Standard im Code 10, die Compose-Datei setzt 5. Kleinere Werte schonen die Server der verbundenen Instanzen, größere arbeiten viele Konten schneller ab.

Weitere Stellschrauben (Reichweite, Zeitlimits, Protokollierung) stehen auf der Seite Umgebungsvariablen.

Minimalbetrieb: nur db + app

Worker sind optional. Betreibst du FediSuite für dich allein oder für eine sehr kleine Gruppe, kannst du auf die Worker-Container verzichten. Das spart Arbeitsspeicher, weil weniger Container laufen.

In der Standarddatei hat der app-Container die Hintergrundjobs abgeschaltet (ENABLE_*=false). Im Minimalbetrieb schaltest du sie dort wieder ein, auch die Reichweiten-Berechnung:

docker-compose.yml: app im Minimalbetrieb
  app:
    image: ${FEDISUITE_IMAGE:?Set FEDISUITE_IMAGE to an explicit version in .env}
    ...
    environment:
      - ENABLE_SCHEDULER=true        # vorher false
      - ENABLE_POSTS_REFRESH=true    # vorher false
      - ENABLE_IDLE_REMINDER=true    # vorher false
      - ENABLE_TIPS_ENGINE=true      # vorher false
      - ENABLE_REACH_REFRESH=true    # vorher false
      - PLUGINS_ENABLED=${PLUGINS_ENABLED:-true}
      - PLUGIN_SCAN_ON_START=${PLUGIN_SCAN_ON_START:-true}
      - PLUGIN_API_VERSION=1

Danach kannst du die worker1- und worker2-Blöcke löschen oder auskommentieren. docker compose up -d startet dann nur noch db und app.

Jederzeit umsteigen möglich. Später kannst du wieder auf Worker wechseln: Worker-Blöcke ergänzen, im app-Container die ENABLE_*-Variablen wieder auf false setzen und docker compose up -d ausführen. Die Daten bleiben dabei erhalten.

Volumes: wo Daten gespeichert werden

Container sind flüchtig: Wird ein Container entfernt, sind seine Daten weg. Volumes verknüpfen einen Ordner auf dem Host mit einem Ordner im Container, damit Daten erhalten bleiben.

FediSuite nutzt ausschließlich Bind Mounts. Die Daten liegen als normale Ordner neben der docker-compose.yml, ein Backup sichert also diese Ordner (siehe Backup & Restore).

./postgres/ /var/lib/postgresql

Genutzt von: db

Alle Datenbankdaten: Nutzer*innen, Beiträge, Entwürfe, Einstellungen, Verknüpfungen zu Fediverse-Konten. Das Wichtigste im gesamten Setup. Der Pfad kommt aus POSTGRES_DATA_PATH (Standard ./postgres), das Ziel im Container aus POSTGRES_DATA_TARGET (PostgreSQL 18: /var/lib/postgresql).

Diesen Ordner niemals löschen. Er enthält alle Datenbankdaten deiner Instanz.
./uploads/ /app/uploads

Genutzt von: app, worker1, worker2

Anhänge zu Beiträgen und Entwürfen. Muss zwischen App und Workern geteilt werden, weil die Worker beim Veröffentlichen darauf zugreifen.

./plugins/ /app/plugins

Genutzt von: app, worker1, worker2

Installierte Plugins (je ein Unterordner mit einer plugin.json).

./logs/ /app/logs

Genutzt von: app, worker1, worker2

Audit-Logs als JSON-Zeilen in monatlichen Dateien (audit-YYYY-MM.log). Teile der E-Mail-Adressen und Handles sind maskiert. Die Logs erscheinen nicht in der Container-Ausgabe.

Rechte: Die Container laufen als UID/GID 1000 (Benutzer node). uploads und logs müssen für diesen Benutzer beschreibbar sein, plugins lesbar, und beschreibbar, wenn du Plugins über die App installierst oder aktualisierst. Lege die Ordner bei einer Neuinstallation mit install -d -m 0750 -o 1000 -g 1000 uploads plugins logs an. Bei bestehenden Ordnern erst ein Backup erstellen, dann den Besitzer anpassen. Starte die Container nicht als Root, um einen Rechtefehler zu umgehen.

Weitere Konzepte erklärt

Warum laufen worker1 und worker2 mit demselben Image wie app?

FediSuite ist eine einzelne Node.js-Anwendung, die je nach Umgebungsvariablen unterschiedliche Rollen übernimmt. Welche Rolle ein Container hat, bestimmen die ENABLE_*-Variablen. Dass nur app von außen erreichbar ist, liegt am veröffentlichten Port in der Compose-Datei, nicht am Image.

Was bedeutet depends_on mit service_healthy?

Ohne diese Bedingung startet Docker alle Container gleichzeitig. Die App würde dann auf die Datenbank zugreifen, bevor PostgreSQL bereit ist. Mit condition: service_healthy wartet jeder abhängige Container auf den bestandenen Healthcheck. Die Worker hängen von db und app ab: Sie starten erst, wenn die App die Migrationen abgeschlossen hat und antwortet, damit nicht Worker und App gleichzeitig am Datenbankschema arbeiten.

Netzwerk: Wie reden die Container miteinander?

Docker Compose legt ein internes Netzwerk an, in dem sich alle Container über ihren Service-Namen erreichen. Die App spricht die Datenbank unter dem Hostnamen db an, deshalb lautet die DATABASE_URL postgresql://…@db:5432/…. Die Datenbank veröffentlicht keinen Port und ist von außen nicht erreichbar.

Traefik-Labels und Netzwerk in der docker-compose.yml

Im app-Service sind Traefik-Labels und die Netzwerk-Einträge auskommentiert vorbereitet. Die Datei docker-compose.traefik.example.yml zeigt dieselben Einträge als Beispiel. Wie du sie anpasst, steht auf der Seite Reverse Proxy.

Gemeinsame Blöcke am Dateianfang (x-… und *…)

Die Datei beginnt mit zwei Blöcken, die mehrere Dienste gemeinsam nutzen. Ein Eintrag wie &default-logging gibt dem Block einen Namen, *default-logging verwendet ihn an anderer Stelle. So steht jede Einstellung nur einmal in der Datei. Willst du etwa die Log-Größe ändern, passt du sie nur dort an:

docker-compose.yml (Anfang)
x-fedisuite-healthcheck: &fedisuite-healthcheck
  test: ["CMD", "node", "--input-type=module", "-e", "try { const response = await fetch('http://127.0.0.1:3000/api/health', { signal: AbortSignal.timeout(3000) }); if (!response.ok) process.exitCode = 1; } catch { process.exitCode = 1; }"]
  interval: 10s
  timeout: 5s
  retries: 5
  start_period: 10m

x-default-logging: &default-logging
  driver: json-file
  options:
    max-size: "25m"
    max-file: "5"

Optional: PostgreSQL für größere Server anpassen

Die Standardwerte von PostgreSQL passen für eine kleine Installation. Auf einem Server mit mehreren GiB Arbeitsspeicher kannst du im db-Dienst die auskommentierten Zeilen shm_size und command aktivieren und die Werte anpassen. Als Faustregel bekommt shared_buffers etwa 25 % des Arbeitsspeichers, den du für PostgreSQL entbehren kannst, und effective_cache_size den Speicher, den das Betriebssystem als Dateicache nutzen kann. Starte danach nur die Datenbank neu (docker compose up -d db) und prüfe docker compose logs db auf Fehler.

docker-compose.yml: db (Beispielwerte, optional)
    shm_size: 512mb
    command:
      - postgres
      - -c
      - shared_buffers=1GB
      - -c
      - effective_cache_size=4GB
      - -c
      - max_wal_size=4GB
      - -c
      - wal_compression=on