---
title: "Plugins installieren"
description: "Plugin-Dateien je Installationsart ablegen (Docker Compose, Portainer, Coolify, Webserver), Dateirechte, Aktivieren im Plattform-Admin oder auf der Konsole"
---

Ein Plugin kommt als Ordner, der wie seine **Plugin-ID** heißt (z. B. `mein-plugin/`), meist als Archiv. Darin liegen mindestens `plugin.json` und `src/`, bei Plugins mit Oberfläche zusätzlich das gebaute `dist/`. Ordner, deren Name mit einem Punkt beginnt, ignoriert QuickTribe – praktisch, um eine vorige Fassung daneben aufzuheben.

<Warning>
Plugins laufen mit allen Rechten der Plattform. Installieren Sie nur Plugins aus vertrauenswürdiger Quelle (siehe [Vertrauen und Sicherheit](/plugins/ueberblick#vertrauen-und-sicherheit)).
</Warning>

## Regeln für die Dateien

QuickTribe lädt ein Plugin nur, wenn

- jede Datei und jeder Ordner **`root` gehört** (uid 0),
- nichts für Gruppe oder andere schreibbar ist (Rechte z. B. `644` für Dateien, `755` für Ordner) und der PHP-Prozess (`www-data`) nichts davon ändern kann,
- es **keine symbolischen Links und keine Hardlinks** enthält.

Lesbar müssen die Dateien für alle sein – sonst kann PHP sie nicht laden. Dasselbe gilt für das Plugin-Verzeichnis selbst. Verstößt etwas dagegen, zeigt der Plattform-Admin den Status **unsicher** mit dem Grund, z. B. „gehört uid 1000 statt 0“ oder „für Gruppe oder andere schreibbar“.

Die passenden Rechte setzen auf dem Host diese beiden Befehle (`<ordner>` = der Plugin-Ordner):

```bash
sudo chown -R root:root <ordner>
sudo chmod -R u+rwX,go+rX,go-w <ordner>
find <ordner> -type l -o -type f -links +1   # muss leer bleiben (keine Links)
```

Plugins mit Oberfläche bringen ihre gebauten Dateien in `dist/` mit. Fehlt `dist/`, meldet der Plattform-Admin einen Fehler. `tests/` und die Quellen der Oberfläche (`frontend/`) braucht der Betrieb nicht.

## Docker Compose (Auslieferungspaket)

Die Stack-Datei bindet den Ordner `plugins/` **neben der `docker-compose.yml`** ein: in `app` und `migrate` nur lesbar, im `worker` schreibbar. Das Auslieferungspaket enthält ihn bereits – mit einer `README.md` und dem [Beispiel-Plugin](/plugins/beispiel-plugin) (inaktiv; wer es nicht braucht, löscht den Ordner `plugins/example-plugin`).

Entpacken Sie das Paket als `root` (z. B. mit `sudo tar -xzf …`), gehören die Dateien bereits `root`. Ein neues Plugin legen Sie so ab:

```bash
cd /opt/quicktribe                                    # Verzeichnis mit docker-compose.yml
sudo tar -xzf ~/mein-plugin-1.0.0.tar.gz -C plugins   # ergibt plugins/mein-plugin/
sudo chown -R root:root plugins
sudo chmod -R u+rwX,go+rX,go-w plugins
docker compose exec app php bin/console app:plugin:validate
```

Fehlt der Ordner `plugins/` (etwa nach einem Update von einer älteren Version), legt Docker ihn beim Start leer an; die Rechte stimmen dann bereits.

<Tip>
Unter Docker Desktop (macOS, Windows) bilden eingebundene Ordner Eigentümer und Schreibrechte nicht wie unter Linux ab – Plugins erscheinen dort meist als „unsicher“. Docker Desktop eignet sich nur zum Ausprobieren, nicht für den Betrieb.
</Tip>

## Portainer und Coolify

Hier liegen Plugins im Docker-Volume `plugins` (bei Portainer `<stack>_plugins`). Es ist in `app` und `migrate` nur lesbar eingehängt; Dateien kommen über den **Worker-Container** hinein. Sie brauchen dafür eine Shell auf dem Docker-Host (SSH).

Den Namen des Worker-Containers zeigt `docker ps --filter name=worker` – bei Portainer `<stack>-worker-1` (z. B. `quicktribe-worker-1`), bei Coolify `worker-` gefolgt von der Kennung der Ressource. In den Beispielen steht `quicktribe-worker-1` bzw. `quicktribe-app-1`.

```bash
tar -xzf mein-plugin-1.0.0.tar.gz                 # ergibt ./mein-plugin
chmod -R u+rwX,go+rX,go-w mein-plugin             # Rechte übernimmt docker cp
docker cp mein-plugin quicktribe-worker-1:/var/www/plugins/mein-plugin
docker exec quicktribe-worker-1 chown -R root:root /var/www/plugins/mein-plugin
docker exec quicktribe-app-1 php bin/console app:plugin:validate
```

`docker cp` legt die Dateien im Container als `root` an und übernimmt die Rechte der Quelle; der `chown` stellt das zusätzlich sicher. Wer lieber mit einem Ordner auf dem Host arbeitet, kann in der Stack-Datei das Volume `plugins` bei allen drei Diensten durch einen Host-Ordner ersetzen (`/opt/quicktribe-plugins:/var/www/plugins:ro` in `app` und `migrate`, ohne `:ro` im `worker`) und dann wie bei [Docker Compose](#docker-compose-auslieferungspaket) vorgehen.

## Webserver ohne Docker

Bei der [Installation auf einem Webserver](/installation/webserver) liegen Plugins außerhalb der Versionsordner, damit sie Updates der Plattform überdauern: in `/var/www/quicktribe/shared/plugins`. Einmal einrichten:

1. Verzeichnis anlegen: `install -d -o root -g root -m 755 /var/www/quicktribe/shared/plugins`
2. In `shared/.env.local` eintragen: `APP_PLUGINS_DIR=/var/www/quicktribe/shared/plugins`
3. In der nginx-Site den Block für `/plugin-assets/` ergänzen (siehe [Webserver → nginx](/installation/webserver#10-nginx-und-tls)) und `nginx -t && systemctl reload nginx`.
4. Den zweiten Worker-Dienst `quicktribe-plugin-worker` einrichten, falls noch nicht geschehen (siehe [Webserver → Worker](/installation/webserver#11-worker)).

Ein Plugin ablegen:

```bash
P=/var/www/quicktribe/shared/plugins
tar -xzf mein-plugin-1.0.0.tar.gz -C $P
chown -R root:root $P && chmod -R u+rwX,go+rX,go-w $P
systemctl reload php8.5-fpm
systemctl restart quicktribe-worker quicktribe-plugin-worker
cd /var/www/quicktribe/current && runuser -u www-data -- php bin/console app:plugin:validate
```

QuickTribe prüft neue Plugin-Fassungen in einem eigenen PHP-Prozess. Dafür muss das Kommandozeilenprogramm `php` installiert sein (Paket `php8.5-cli`) und PHP darf Prozesse starten (`proc_open` nicht in `disable_functions`).

## Aktivieren

Unter **Plattform-Admin → Plugins** erscheint das Plugin mit dem Status **inaktiv**. Mit **Aktivieren** führt QuickTribe die Migrationen des Plugins aus (legt seine Tabellen an) und schaltet es plattformweit ein; der Status wechselt auf **aktiv**.

- **Erneute Anmeldung:** Aktivieren und **Migrationen ausführen** verlangen eine Anmeldung innerhalb der letzten 10 Minuten („angemeldet bleiben“ zählt nicht). Sonst erscheint der Hinweis, sich ab- und wieder anzumelden und es innerhalb von 10 Minuten erneut zu versuchen.
- **Je Community:** Plugins mit der Angabe „einzelne Communities (Opt-in)“ sind danach in jeder Community **aus**; Owner und Admins schalten sie unter **Einstellungen → Plugins** ein (siehe [Einstellungen → Plugins](/handbuch/owner/plugins)). Plugins für „alle Communities“ wirken sofort überall.
- **Datenschutz:** Verarbeitet ein Plugin personenbezogene Daten, steht das in der Übersicht. Owner sollten dann ihre Datenschutzerklärung prüfen; die Vorlage unter Einstellungen → Rechtstexte enthält einen Absatz des Plugins.

Dasselbe auf der Konsole (ohne erneute Anmeldung, protokolliert mit Herkunft Konsole):

```bash
php bin/console app:plugin:list                                # alle Plugins mit Status
php bin/console app:plugin:enable mein-plugin                  # plattformweit, mit Migrationen
php bin/console app:plugin:enable mein-plugin --community=demo # zusätzlich in /c/demo einschalten
php bin/console app:plugin:disable mein-plugin                 # plattformweit aus (Daten bleiben)
```

Wo Sie Konsolenbefehle eingeben, steht unter [Betrieb → Konsole](/betrieb#konsole). Alles Weitere – Migrationen, Updates, Entfernen, Worker und Fehlersuche – beschreibt [Plugins betreiben](/plugins/betrieb).
