Plugin Installation for Self-Hosters#

Barazo supports extending your forum with plugins. Plugins are npm packages installed into a persistent Docker volume.

Quick Start#

1. Copy the example plugin configuration:

   cp plugins.json.example plugins.json
   

2. Edit plugins.json to declare the plugins you want:

   {
     "plugins": [
       {
         "name": "@barazo/plugin-polls",
         "version": "^1.0.0"
       }
     ]
   }
   

3. Restart the API container to install plugins:

   docker compose restart barazo-api
   

The install-plugins.sh script runs on startup. It reads plugins.json and installs each declared plugin into the plugins volume at /app/plugins/.

plugins.json Format#

{
  "plugins": [
    {
      "name": "@barazo/plugin-polls",
      "version": "^1.0.0"
    },
    {
      "name": "community-badges",
      "version": "2.0.0"
    }
  ]
}

Each entry requires:

• name -- the npm package name (scoped or unscoped)
• version -- a semver range (optional; defaults to latest)

How It Works#

• plugins.json is bind-mounted read-only into the container at /app/plugins.json
• On startup, install-plugins.sh reads the file and runs npm install for each plugin
• Plugins are installed into the plugins Docker volume at /app/plugins/
• The volume persists across container restarts -- plugins are not reinstalled unless the version changes
• If plugins.json is missing or empty, no plugins are installed and the forum runs normally

Enabling and Configuring Plugins#

After installation, enable plugins through the admin UI:

1. Go to Admin > Plugins
2. Find the installed plugin in the Installed tab
3. Toggle it on
4. Configure plugin-specific settings if available

Adding a New Plugin#

1. Add the plugin to plugins.json
2. Restart the API: docker compose restart barazo-api
3. Enable it in the admin UI

Removing a Plugin#

1. Remove the plugin entry from plugins.json
2. Disable it in the admin UI
3. Restart the API: docker compose restart barazo-api

To fully remove installed files, delete the plugins volume and restart:

docker compose down
docker volume rm barazo_plugins
docker compose up -d

This reinstalls only the plugins declared in plugins.json.

Troubleshooting#

Plugin fails to install:

Check the API container logs:

docker compose logs barazo-api | grep install-plugins

Common causes:

• Invalid package name in plugins.json
• Network connectivity issues (the container needs access to the npm registry)
• Version not found on npm

Plugin installed but not showing in admin:

Ensure PLUGINS_ENABLED=true is set in your .env file (this is the default).