WebSocket bridge between the Flowly plugin running in the BigBlueButton client and the BBB backend (bbb-web, Redis/Akka, PostgreSQL). It runs on the BigBlueButton server itself.
Plain Node.js (CommonJS), three runtime dependencies: ws, pg, ioredis.
- Authenticates each connection with the participant's BBB session token, by asking bbb-web.
- Routes
module:actionevents from the plugin to small handlers inmodules/. - Pushes events back to one participant or to the whole meeting.
- Follows role changes (moderator promotions) from the Akka Redis channel.
Current modules:
| Event | Who can call it | Effect |
|---|---|---|
user:rename |
Anyone for themselves; moderators for any participant of their meeting | Updates the name in the BBB database and notifies the meeting |
example:hello |
Anyone | Returns a greeting; shows the module contract |
| Direction | Type | Shape |
|---|---|---|
| Client→Server | connection_init |
{ type, payload: { sessionToken } } |
| Server→Client | connection_ack |
{ type, user, meeting } |
| Client→Server | event |
{ type, id, event: "module:action", payload } |
| Server→Client | response |
{ type, id, data } |
| Server→Client | error |
{ type, id, error: { code, message } } |
| Server→Client | push |
{ type, event, data } |
Before connection_ack, every message other than connection_init is ignored. Close codes:
4401 unauthorized, 4408 timeout, 4410 meeting ended, 4500 internal error.
See .env.example. The defaults target a standard BBB 3.x server where bbb-web,
Redis and PostgreSQL listen on 127.0.0.1.
The user:rename handler writes to the BBB bbb_graphql database. Create a dedicated role for it
instead of using postgres:
sudo -u postgres psql -d bbb_graphql -c "
CREATE USER flowly WITH PASSWORD '<strong-password>';
GRANT CONNECT ON DATABASE bbb_graphql TO flowly;
GRANT USAGE ON SCHEMA public TO flowly;
GRANT SELECT, UPDATE ON TABLE \"user\" TO flowly;
"pnpm install
cp .env.example .env
pnpm dev # nodemon, reads .env (Node.js 20.6+)
pnpm lintWith bbb-docker, use the container IPs given in
.env.example.
pnpm build:deb (needs dpkg-deb and fakeroot) produces dist/flowly-plugin-server_<version>_all.deb.
The package installs to /usr/local/bigbluebutton/flowly-plugin-server, creates a
flowly-plugin-server systemd service and an nginx snippet that proxies /flowly-plugin-server
to 127.0.0.1:8094.
sudo apt install ./dist/flowly-plugin-server_<version>_all.deb
sudo nano /usr/local/bigbluebutton/flowly-plugin-server/.env
sudo ln -s /etc/nginx/sites-available/flowly-plugin-server.conf /etc/bigbluebutton/nginx/flowly-plugin-server.nginx
sudo systemctl restart flowly-plugin-server nginxCreate modules/<name>/index.js exporting { events: { action: handler } }, plus optional
onLoad(coreServices) / onUnload() hooks. A handler is async (ctx, payload) => data; throw an
Error with a code property (UNAUTHORIZED, INVALID_PAYLOAD, …) to return an error. ctx
exposes user, meeting, pg, redis, push, broadcast and publishToAkka. Handlers time
out after 10 seconds.
Always scope database access to ctx.meeting.id: one BBB server hosts many meetings.