Installing Plugins

Plugins are optional extensions for FediSuite. The core installation remains completely unchanged — plugins are maintained separately and integrated via Docker without modifying the main Docker image. This means FediSuite itself can be updated without any problems, regardless of which plugins you use.

All official plugins are maintained in the christinloehner/FediSuite-Plugins repository. A single git clone of this repository installs all available plugins at once — but only those that you actually enable in FediSuite will be active.

Before installing plugins, make sure FediSuite is already running and the following prerequisites are met:

Navigate to your FediSuite installation folder — the directory where your docker-compose.yml is located. Clone the plugin repository there as a subfolder named plugins:

cd /path/to/your/fedisuite-folder
git clone https://codeberg.org/christinloehner/FediSuite-Plugins.git plugins

Verify that the folder was created correctly:

ls -la plugins/

You should see something like this:

drwxr-xr-x  .git/
-rw-r--r--  LICENSE
-rw-r--r--  PLUGIN-AUTHORING.de.md
-rw-r--r--  PLUGIN-AUTHORING.md
-rw-r--r--  README.de.md
-rw-r--r--  README.md
drwxr-xr-x  fedisuite-plugin-bluesky/

Your folder structure should look like this after this step:

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

FediSuite runs entirely in Docker containers. For these containers to be able to see and use the plugins folder, it must be mounted as a volume. A volume is essentially a shared connection between a folder on your server and a path in the container — the container can then read this folder as if it were part of its own file system.

Open your docker-compose.yml with a text editor and add the following line to the volumes: section of all three services (app, worker1 and worker2):

- ./plugins:/app/plugins

Here's how the three services look after the update:

  app:
    image: ${FEDISUITE_IMAGE:-christinloehner/fedisuite:latest}
    ...
    volumes:
      - ./uploads:/app/uploads
      - ./plugins:/app/plugins    ← add this line

  worker1:
    image: ${FEDISUITE_IMAGE:-christinloehner/fedisuite:latest}
    ...
    volumes:
      - ./uploads:/app/uploads
      - ./plugins:/app/plugins    ← add this line

  worker2:
    image: ${FEDISUITE_IMAGE:-christinloehner/fedisuite:latest}
    ...
    volumes:
      - ./uploads:/app/uploads
      - ./plugins:/app/plugins    ← add this line

docker compose config | grep plugins

Restart the containers so Docker reads the updated docker-compose.yml and activates the plugin volume. Plugins are automatically detected and loaded by FediSuite when the container starts.

docker compose up -d

docker compose up -d --force-recreate

After restarting, you can verify that plugins were loaded correctly in two ways: through the FediSuite interface or through the container logs.

Option 1 — Via the FediSuite interface

Option 2 — Via container logs

docker compose logs app | grep -i plugin

If plugins were detected, corresponding messages will appear in the app logs. An empty result means either no plugins were loaded or FediSuite logs minimally about plugins.

docker compose ps                        # are all containers running?
docker compose config | grep plugins     # is the plugin mount active?

Since plugins are managed as a Git repository, updating is simple: git pull in the plugins folder fetches all changes, then restart the containers.

cd plugins
git pull
cd ..
docker compose up -d

There are two options: permanently delete a single plugin or temporarily disable all plugins.

rm -rf plugins/fedisuite-plugin-bluesky
docker compose up -d

    volumes:
      - ./uploads:/app/uploads
      # - ./plugins:/app/plugins    ← commented out

docker compose up -d

If a plugin doesn't appear in the admin area after installation, go through this checklist:

Common error sources 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                        # all containers running?
docker compose logs app                  # check app logs for errors
docker compose logs app | grep -i plugin # search specifically for plugin messages