Installing Plugins

Plugins are optional extensions for FediSuite. Each plugin is a folder containing a plugin.json. All plugin folders live in the plugins/ directory next to your docker-compose.yml and are mounted into the containers as a volume at /app/plugins. The Docker image stays unchanged, so you can update FediSuite independently of your plugins.

The plugins are maintained in the FediSuite/FediSuite-Plugins-Repository ↗ (opens in new tab) repository on Forgejo. A single git clone fetches every plugin it contains. Newly detected plugins start out disabled. Only what an admin switches on in plugin management becomes active.

Before you install plugins, FediSuite should already be running and the following should be in place:

Change into your FediSuite installation folder, that is, the folder that contains your docker-compose.yml, and clone the plugin repository as a subfolder named plugins:

cd /path/to/your/fedisuite-folder
git clone https://forge.chrislo.de/FediSuite/FediSuite-Plugins-Repository.git plugins

Then check that the folder was created correctly:

ls -la plugins/

Among other things, you should see these entries:

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

Your folder structure now looks like this:

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

For the containers to see the plugins folder, it has to be mounted as a volume. The docker-compose.yml from the self-hosting repository already contains the mount for the three services app, worker1 and worker2 and also sets the plugin variables. All three containers read the plugin folder themselves at startup, which is why each of them needs the mount.

This is the excerpt for app in the default file (worker1 and worker2 contain the same plugin lines):

  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

Use this command to check that the mount is active. The output lists the path to plugins and the target /app/plugins for each of the three services:

docker compose config | grep plugins

FediSuite only reads the plugin folder when the containers start. After cloning, app, worker1 and worker2 therefore have to restart. If the Compose file already contained the mount and you have not changed it, restarting these containers is enough:

docker compose restart app worker1 worker2

If you changed docker-compose.yml (for example by adding the mount), re-read it with this command. It recreates the affected containers:

docker compose up -d

Detected plugins are switched off after installation. Sign in as an admin, open Admin area → / Plugins in the sidebar and click Enable on the plugin you want. The plugin starts right away in the running application, so the web interface needs no restart. More details are on the Plugin Management page.

After the restart you can see in the FediSuite interface or in the container logs whether the plugins were detected.

Option 1: In the FediSuite interface

Option 2: In the container logs

docker compose logs app | grep -i plugin

After the scan, FediSuite reports something like Plugin discovery finished. 2 plugin directory/directories scanned. The number is the count of folders found that contain a plugin.json. If the mount is missing entirely, you will see Plugin directory /app/plugins does not exist instead. If the plugin system is switched off through PLUGINS_ENABLED or PLUGIN_SCAN_ON_START, a message names the variable concerned. Why an individual plugin does not start is not written to the logs. It appears as an error message in the expanded details of plugin management.

docker compose ps                        # are all containers running?
docker compose config | grep plugins     # is the plugin mount active?
docker compose exec app ls /app/plugins  # what does the container see?

Because the plugin folder is a Git repository, git pull fetches all changes. The containers then have to restart, since plugins are only re-read at startup. A plain docker compose up -d does not restart unchanged containers and is therefore not enough.

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

There are three ways: disable a single plugin, delete a single plugin permanently, or switch off the whole plugin system.

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

    environment:
      - PLUGINS_ENABLED=false    # before: true

docker compose up -d

If a plugin does not appear in plugin management after installation, work through this checklist:

Common causes at a glance

ls -la plugins/                          # folder present and contents correct?
ls -la plugins/fedisuite-plugin-bluesky/ # plugin.json present?
docker compose config | grep plugins     # volume mount configured?
docker compose ps                        # are all containers running?
docker compose exec app ls /app/plugins  # what does the container see?
docker compose logs app                  # check app logs for errors
docker compose logs app | grep -i plugin # search for plugin messages