Plugins installieren

Plugins sind optionale Erweiterungen für FediSuite. Jedes Plugin ist ein Ordner mit einer plugin.json. Alle Plugin-Ordner liegen im Verzeichnis plugins/ neben der docker-compose.yml und werden per Volume nach /app/plugins in die Container eingebunden. Das Docker-Image bleibt unverändert, FediSuite lässt sich also unabhängig von den Plugins aktualisieren.

Die Plugins werden im Repository FediSuite/FediSuite-Plugins-Repository ↗ (öffnet in neuem Tab) auf Forgejo gepflegt. Ein einziges git clone holt alle darin enthaltenen Plugins. Neu erkannte Plugins sind zunächst deaktiviert. Aktiv wird nur, was ein Admin in der Plugin-Verwaltung einschaltet.

Bevor Du Plugins installierst, sollte FediSuite bereits laufen und Folgendes vorhanden sein:

Wechsle in Deinen FediSuite-Installationsordner, also dorthin, wo die docker-compose.yml liegt, und klone das Plugin-Repository als Unterordner mit dem Namen plugins:

cd /pfad/zu/deinem/fedisuite-ordner
git clone https://forge.chrislo.de/FediSuite/FediSuite-Plugins-Repository.git plugins

Prüfe anschließend, ob der Ordner korrekt angelegt wurde:

ls -la plugins/

Darin sollten unter anderem diese Einträge stehen:

.git/
LICENSE
PLUGIN-AUTHORING.de.md
PLUGIN-AUTHORING.md
README.de.md
README.md
fedisuite-plugin-bluesky/
my-plugin/

Die Ordnerstruktur sieht danach so aus:

fedisuite/
├── .env
├── docker-compose.yml
├── logs/
├── postgres/
├── uploads/
└── plugins/                      ← neu geklont
    ├── .git/
    ├── fedisuite-plugin-bluesky/
    │   └── plugin.json
    ├── my-plugin/
    │   └── plugin.json
    ├── README.md
    └── README.de.md

Damit die Container den Ordner plugins sehen, muss er als Volume eingebunden sein. Die docker-compose.yml aus dem Self-Hosting-Repository enthält den Mount bereits bei den drei Services app, worker1 und worker2 und setzt außerdem die Plugin-Variablen. Alle drei Container lesen den Plugin-Ordner beim Start selbst ein, deshalb braucht jeder von ihnen den Mount.

So sieht der Auszug für app in der Standard-Datei aus (bei worker1 und worker2 stehen dieselben Plugin-Zeilen):

  app:
    image: ${FEDISUITE_IMAGE:-christinloehner/fedisuite:latest}
    ...
    environment:
      - PLUGINS_ENABLED=true
      - PLUGIN_SCAN_ON_START=true
      - PLUGIN_API_VERSION=1
    ...
    volumes:
      - ./uploads:/app/uploads
      - ./plugins:/app/plugins
      - ./logs:/app/logs

Mit diesem Befehl prüfst Du, ob der Mount aktiv ist. Die Ausgabe nennt für jeden der drei Services den Pfad zu plugins und das Ziel /app/plugins:

docker compose config | grep plugins

FediSuite liest den Plugin-Ordner nur beim Start der Container ein. Nach dem Klonen müssen deshalb app, worker1 und worker2 neu starten. Wenn die Compose-Datei bereits den Mount enthielt und Du sie nicht geändert hast, reicht ein Neustart dieser Container:

docker compose restart app worker1 worker2

Hast Du die docker-compose.yml geändert (zum Beispiel den Mount ergänzt), lies sie mit diesem Befehl neu ein. Er erstellt die betroffenen Container neu:

docker compose up -d

Erkannte Plugins sind nach der Installation ausgeschaltet. Melde Dich als Admin an, öffne in der Seitenleiste Admin-Bereich → / Plugins und klicke beim gewünschten Plugin auf Aktivieren. Das Plugin startet sofort in der laufenden Anwendung, ein Neustart ist für die Weboberfläche nicht nötig. Details dazu stehen unter Plugin-Verwaltung.

Nach dem Neustart siehst Du in der FediSuite-Oberfläche oder in den Container-Logs, ob die Plugins erkannt wurden.

Option 1: Über die FediSuite-Oberfläche

Option 2: Über die Container-Logs

docker compose logs app | grep -i plugin

Nach dem Scan meldet FediSuite zum Beispiel Plugin discovery finished. 2 plugin directory/directories scanned. Die Zahl nennt die gefundenen Ordner mit einer plugin.json. Fehlt der Mount ganz, steht dort stattdessen Plugin directory /app/plugins does not exist. Ist das Plugin-System über PLUGINS_ENABLED oder PLUGIN_SCAN_ON_START abgeschaltet, nennt eine Meldung die jeweilige Variable. Warum ein einzelnes Plugin nicht startet, steht nicht in den Logs, sondern als Fehlermeldung in den aufgeklappten Details der Plugin-Verwaltung.

docker compose ps                        # laufen alle Container?
docker compose config | grep plugins     # ist der Plugin-Mount aktiv?
docker compose exec app ls /app/plugins  # was sieht der Container?

Da der Plugin-Ordner ein Git-Repository ist, holt git pull alle Änderungen. Danach müssen die Container neu starten, denn Plugins werden erst beim Start neu eingelesen. Ein einfaches docker compose up -d startet unveränderte Container nicht neu und reicht deshalb nicht.

cd plugins
git pull
cd ..
docker compose restart app worker1 worker2

Es gibt drei Wege: ein einzelnes Plugin deaktivieren, ein einzelnes Plugin dauerhaft löschen oder das gesamte Plugin-System abschalten.

rm -rf plugins/fedisuite-plugin-bluesky
docker compose restart app worker1 worker2

    environment:
      - PLUGINS_ENABLED=false    # vorher: true

docker compose up -d

Wenn ein Plugin nach der Installation nicht in der Plugin-Verwaltung erscheint, gehe diese Checkliste durch:

Häufige Fehlerquellen im Überblick

ls -la plugins/                          # Ordner vorhanden und Inhalt korrekt?
ls -la plugins/fedisuite-plugin-bluesky/ # plugin.json vorhanden?
docker compose config | grep plugins     # Volume-Mount konfiguriert?
docker compose ps                        # alle Container laufen?
docker compose exec app ls /app/plugins  # was sieht der Container?
docker compose logs app                  # App-Logs auf Fehler prüfen
docker compose logs app | grep -i plugin # gezielt nach Plugin-Meldungen suchen