Configure the BigBlueButton Cluster Proxy

01

Choose the supported integration path

The cluster proxy serves each node’s HTML5 client beneath a common origin. WebSockets, slides and media still travel to the assigned backend. It can reduce repeated browser permission prompts, but does not hide backend hostnames or replace Scalelite.

• Working load-balanced BBB cluster.
• Unique path basename for every backend node.
• Proxy hostname, HTTPS and direct client reachability to all BBB nodes.

02

Prepare BigBlueButton and credentials

Use a production BigBlueButton endpoint with a trusted TLS certificate. Keep the API shared secret or LTI secret on the server side: it is equivalent to an application credential and must never be placed in browser code, a public repository or a screenshot.

1. 1

   Confirm the BigBlueButton server is healthy and that its public hostname resolves correctly.

2. 2

   Retrieve the API URL and shared secret with sudo bbb-conf --secret, or create a dedicated LTI key and secret where the integration uses LTI.

3. 3

   Record the platform version, connector version, owner and rollback point before making the change.

sudo bbb-conf --check
sudo bbb-conf --secret

03

Configure Cluster Proxy

Make the first connection in a staging course, workspace or tenant. Use a dedicated test teacher and test learner so role mapping can be observed rather than inferred from an administrator account.

1. 1

   Add one nginx location per backend using the path pattern in the official guide.

2. 2

   Set defaultHTML5ClientUrl, presentationBaseURL, accessControlAllowOrigin and guest URL on each node.

3. 3

   Set the matching basename in bbb-html5.yml and apply configuration with bbb-conf.

4. 4

   Repeat consistently for every node; automate generation to prevent path drift.

04

Run an end-to-end acceptance test

A green “connection successful” message proves only that one API request worked. The useful test follows the complete classroom lifecycle from creation through recording publication.

1. 1

   Create meetings on each backend through the load balancer.

2. 2

   Inspect the HTML5 asset origin and verify media candidates still point to the assigned backend.

3. 3

   Test microphone/camera permissions across meetings placed on different nodes.

4. 4

   Test presentations, guest waiting, reconnect and websocket recovery.

05

Common problems and practical fixes

Start with timestamps, browser developer tools and the logs on both sides. Repeatedly replacing secrets rarely fixes a hostname, TLS, role or callback problem and makes the evidence harder to follow.

• A blank client commonly means proxy path and bbb-html5 basename do not match.
• CORS failures indicate accessControlAllowOrigin or presentation URL drift.
• Proxying media through this nginx pattern defeats the documented scaling model.

06

Production hardening and upgrades

Restrict who can create rooms, define recording retention, test accessibility and document the integration owner. Pin or approve connector updates, subscribe to upstream releases and repeat the acceptance test after changes to the LMS, connector, BigBlueButton or reverse proxy.

• Do not expose the BigBlueButton shared secret to course authors or client-side JavaScript.
• Use least-privilege teacher roles and test guest, suspended and unenrolled users.
• Monitor API errors, failed joins, recording processing and disk growth.
• Keep a short rollback runbook: previous package, configuration backup and maintenance window.