gui.do
Barazo Docker Compose templates for self-hosting
barazo.forum
1# Plugin Installation for Self-Hosters
2
3Barazo supports extending your forum with plugins. Plugins are npm packages installed into a persistent Docker volume.
4
5## Quick Start
6
71. Copy the example plugin configuration:
8
9 ```bash
10 cp plugins.json.example plugins.json
11 ```
12
132. Edit `plugins.json` to declare the plugins you want:
14
15 ```json
16 {
17 "plugins": [
18 {
19 "name": "@barazo/plugin-polls",
20 "version": "^1.0.0"
21 }
22 ]
23 }
24 ```
25
263. Restart the API container to install plugins:
27
28 ```bash
29 docker compose restart barazo-api
30 ```
31
32The `install-plugins.sh` script runs on startup. It reads `plugins.json` and installs each declared plugin into the `plugins` volume at `/app/plugins/`.
33
34## plugins.json Format
35
36```json
37{
38 "plugins": [
39 {
40 "name": "@barazo/plugin-polls",
41 "version": "^1.0.0"
42 },
43 {
44 "name": "community-badges",
45 "version": "2.0.0"
46 }
47 ]
48}
49```
50
51Each entry requires:
52
53- `name` -- the npm package name (scoped or unscoped)
54- `version` -- a semver range (optional; defaults to `latest`)
55
56## How It Works
57
58- `plugins.json` is bind-mounted read-only into the container at `/app/plugins.json`
59- On startup, `install-plugins.sh` reads the file and runs `npm install` for each plugin
60- Plugins are installed into the `plugins` Docker volume at `/app/plugins/`
61- The volume persists across container restarts -- plugins are not reinstalled unless the version changes
62- If `plugins.json` is missing or empty, no plugins are installed and the forum runs normally
63
64## Enabling and Configuring Plugins
65
66After installation, enable plugins through the admin UI:
67
681. Go to **Admin > Plugins**
692. Find the installed plugin in the **Installed** tab
703. Toggle it on
714. Configure plugin-specific settings if available
72
73## Adding a New Plugin
74
751. Add the plugin to `plugins.json`
762. Restart the API: `docker compose restart barazo-api`
773. Enable it in the admin UI
78
79## Removing a Plugin
80
811. Remove the plugin entry from `plugins.json`
822. Disable it in the admin UI
833. Restart the API: `docker compose restart barazo-api`
84
85To fully remove installed files, delete the plugins volume and restart:
86
87```bash
88docker compose down
89docker volume rm barazo_plugins
90docker compose up -d
91```
92
93This reinstalls only the plugins declared in `plugins.json`.
94
95## Troubleshooting
96
97**Plugin fails to install:**
98
99Check the API container logs:
100
101```bash
102docker compose logs barazo-api | grep install-plugins
103```
104
105Common causes:
106- Invalid package name in `plugins.json`
107- Network connectivity issues (the container needs access to the npm registry)
108- Version not found on npm
109
110**Plugin installed but not showing in admin:**
111
112Ensure `PLUGINS_ENABLED=true` is set in your `.env` file (this is the default).