How to Configure Etherpad Integration in BigBlueButton

Etherpad integration in BigBlueButton is configured through the server’s shared-notes component. On BigBlueButton 4.0 beta.4, Etherpad is optional: install the bbb-pads and bbb-etherpad packages, then select Etherpad for one meeting or set it as the server-wide default. On earlier installations where the Etherpad packages are already present, the main task is choosing the editor and restarting the affected services.

First confirm your BigBlueButton release. The current 4.0 documentation describes a change from the earlier default: BlockNote is the default shared-notes editor, while Etherpad packages are optional. Therefore, explicitly selecting Etherpad avoids relying on a release-specific default. See the official BigBlueButton 4.0 new-features notes and the BigBlueButton API reference.

What the integration does

BigBlueButton presents shared notes inside a meeting and coordinates access to the notes pad. Etherpad provides the live collaborative editor used in that area. In a standard packaged installation, BigBlueButton’s Etherpad components are installed on the same server; you do not normally add a separate public Etherpad URL or paste an Etherpad API key into the meeting interface.

This guide covers the packaged server setup and the supported meeting-level and server-wide choices. A cluster or reverse-proxy deployment needs additional URL and origin configuration; its settings are not a substitute for installing and enabling the Etherpad components.

1. Check your BigBlueButton version and installed packages

Run these commands on the BigBlueButton host:

sudo bbb-conf --check
dpkg -l | grep -E 'bbb-(etherpad|pads|shared-notes-server)'

The package list helps distinguish an absent Etherpad installation from a selection problem. On a BigBlueButton 4.0 beta.4 system, the official notes identify bbb-shared-notes-server (BlockNote) as the required default and bbb-etherpad plus bbb-pads as optional packages. Earlier releases may show a different package mix, so use documentation for the release actually installed rather than copying 4.0 instructions onto an older server.

2. Install Etherpad packages when needed

On BigBlueButton 4.0 beta.4, install the optional packages with APT:

sudo apt update
sudo apt install bbb-pads bbb-etherpad

Review the package manager’s proposed changes before confirming. If APT cannot find either package, check that the BigBlueButton repository is configured for the same release as the server. Do not download a package built for a different BigBlueButton version just to make installation proceed.

After installation, confirm that both packages appear in the package list. If you are upgrading an existing production server, follow the release’s official upgrade procedure and schedule a maintenance window; installing optional packages is a server change, not a meeting-client setting.

3. Enable Etherpad for one meeting

To use Etherpad in a specific session while leaving the server’s default unchanged, set the sharedNotesEditor parameter to etherpad on that meeting’s BigBlueButton create API call:

sharedNotesEditor=etherpad

The parameter belongs in the server-side integration that creates the meeting. The application must include it in the signed create request before calculating the API checksum. BigBlueButton’s API accepts etherpad or blockNote for this option. Check the API documentation for the behavior of your installed release because validation and defaults can differ by version.

Keep the BigBlueButton shared secret on the server. Do not expose it in browser JavaScript, page source, or a mobile client. Anyone who obtains the secret can create signed API calls as your server. If you use Greenlight or another meeting front end, configure the parameter through that integration’s supported settings rather than editing a meeting URL in the browser.

4. Make Etherpad the server-wide default

If every meeting should use Etherpad, edit the BigBlueButton web override file:

sudo nano /etc/bigbluebutton/bbb-web.properties

Add this line, preserving other settings in the file:

sharedNotesEditor=etherpad

Save the file and restart BigBlueButton:

sudo bbb-conf --restart

This setting applies to meetings that do not supply their own sharedNotesEditor value. A meeting-level create parameter can make the choice explicit for a particular session. The official 4.0 notes document this same property for selecting Etherpad globally and specify restarting with bbb-conf --restart.

5. Test the result in a fresh meeting

Use a new test meeting after restarting; an already-running room may not reflect a changed default. Join as a moderator and a second participant, open Shared Notes, and confirm that both users can see and edit the same pad. Make a short test edit from each account, wait for the other participant’s view to update, and verify the result after closing and reopening the notes panel.

If you are testing a meeting created through an API integration, inspect that integration’s create request and confirm it included sharedNotesEditor=etherpad. For a global-default test, create a meeting without setting the parameter. This separates a missing meeting-level option from a server-wide configuration issue.

Cluster proxy and external URL deployments

When browsers reach BigBlueButton through a cluster proxy or a different public hostname, shared-notes URLs and browser origins must match the proxy design. BigBlueButton’s official cluster proxy guide documents the pads.url setting in /etc/bigbluebutton/bbb-html5.yml and a cluster-proxy allowlist in /etc/bigbluebutton/etherpad.json. Its example URL uses a /pad path on the public proxy host. Follow that guide as a whole for the cluster setup, including its origin and proxy requirements; do not copy only the URL line into an unrelated single-server installation.

After changing a cluster configuration, follow the restart and verification steps for the installed BigBlueButton version. If Etherpad loads on the server’s direct hostname but fails through the proxy, investigate the proxy route, hostname, TLS certificate, and browser origin policy before changing the editor selection. A reverse proxy must also support the connections needed by Etherpad’s live editing interface.

Troubleshooting common failures

• Shared Notes opens in BlockNote. Confirm that the meeting used sharedNotesEditor=etherpad, or that sharedNotesEditor=etherpad is present in /etc/bigbluebutton/bbb-web.properties for the global default. On 4.0 beta.4, verify the two optional packages are installed.
• The notes panel is missing or does not load. Run sudo bbb-conf --check, review the package state, and inspect the BigBlueButton and Etherpad service logs for startup or connection errors. Confirm that the browser is using the intended hostname and secure HTTPS origin.
• One participant can edit but another cannot. Test with a fresh meeting and accounts from separate browsers. Check that both users joined the same meeting and that a proxy or authentication layer is not blocking Etherpad’s session or WebSocket traffic.
• Changes do not appear after configuration edits. Create a new meeting after the restart. Also check whether the meeting creator is passing an explicit editor value that overrides the server default.
• It works directly but fails behind a proxy. Compare the public notes URL, proxy route, TLS setup, allowed origin, and cluster configuration with the official cluster-proxy guide. Avoid broad proxy rules that expose unrelated internal services.

Operational and security checks

Keep BigBlueButton, Etherpad packages, and the operating system on supported update paths. Restrict administrative API secrets to trusted server-side code, use HTTPS for the public meeting and notes endpoints, and expose only the routes required by your deployment. If your service records meetings, test how shared notes are handled in recordings and after meetings end; recording behavior can depend on the BigBlueButton release and recording configuration.

Configuration is complete when a fresh meeting selects the intended editor, multiple participants can collaborate, browser console and server logs show no connection failures, and the result remains consistent after reopening the notes panel. For a 4.0 beta.4 deployment, the key change is that Etherpad must be installed as an optional component and selected explicitly. For other releases, verify package and API behavior against that release’s documentation before changing a production server.