From 191f30819b935c6de8d59840816c8ca35b0a7145 Mon Sep 17 00:00:00 2001 From: Andrew Morgan Date: Fri, 7 May 2021 13:05:46 +0100 Subject: [PATCH] Add BigBlueButton usage documentation --- docs/bigbluebutton.md | 102 ++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 102 insertions(+) create mode 100644 docs/bigbluebutton.md diff --git a/docs/bigbluebutton.md b/docs/bigbluebutton.md new file mode 100644 index 0000000..f2a9ba2 --- /dev/null +++ b/docs/bigbluebutton.md @@ -0,0 +1,102 @@ +# BigBlueButton + +[BigBlueButton](https://bigbluebutton.org/) is open-source video calling software aimed primarily at educators and has +useful features such as screen and PDF sharing, collaborative document editing, polls and more. + +Dimension supports embedding BigBlueButton meetings into a Matrix room via widgets, and can do so in two ways: + +* [Greenlight](https://docs.bigbluebutton.org/greenlight/gl-overview.html) is a frontend for BigBlueButton meeting + administration that allows for creating/ending meetings, inviting people via link or email etc. Dimension supports + taking a Greenlight URL and turning it into a widget in a Matrix room that room occupants can use to join the meeting. + In this instance, Greenlight is acting as a client of BigBlueButton's server-side API, and Dimension is relying on a + Greenlight URL to allow Matrix users to join a meeting. +* Alternatively, Dimension can be configured to connect directly to BigBlueButton and create meetings itself. This does + require running your own BigBlueButton server which Dimension will have authorization to control. This configuration is + useful as meetings can be created without needing to leave your Matrix client, as well as sidesteps the need to set up + Greenlight on your deployment. This method can also be used to allow the 'Video Call' button in Element to start a + meeting. + +Note that with the first method, Dimension can be given a Greenlight URL pointing to any public instance of +Greenlight/BigBlueButton. With the second, Dimension will only talk to, and create meetings on, the BigBlueButton server +it has been configured to talk to. + +## Usage Guide + +### Using a Greenlight URL + +Dimension does not require any extra configuration to allow creating meetings using a Greenlight URL. + +* Open the integration manager window and add a BigBlueButton widget. +* Enter the URL you received from Greenlight. It should be in the form: `https://bbb.example.com/abc-def-ghi`. +* Click the 'Add Widget' button. + +Members in the room will see a BigBlueButton widget appear. They can click "Join Conference" inside the widget to join. + +### Have Dimension Create Meetings (with Element's Video Call button) + +Fill out the `bigbluebutton` section of Dimension's config file. Both the `apiBaseUrl` and `sharedSecret` fields must be +set to the values corresponding to your own BigBlueButton server. + +Note: Matrix clients can create widgets by sending a widget state event in the room with the appropriate fields. To retrieve +the necessary content of the state event, clients can +call `/api/v1/dimension/bigbluebutton/widget_state?roomId=!room:domain` +on Dimension to retrieve the necessary state. The contents of the `widget` field from the response is what should be +placed in the `content` of the widget state event. Note that while servicing this call, Dimension will create the +BigBlueButton meeting. The contents of the state event will then contain all necessary information for clients to join +the meeting. + +Element can be configured to do the above automatically without any client-side changes. Simply add the following +information to the [Client well-known](https://matrix.org/docs/spec/client_server/r0.6.1#get-well-known-matrix-client) +file of your homeserver: + +```json +"io.element.call_behaviour": { + "widget_build_url": "https://dimension.example.com/api/v1/dimension/bigbluebutton/widget_state", +} +``` + +then close and reopen Element so that it picks up the new behaviour. + +Now pressing the Video Call button in a room with more than two users in it should spawn a BigBlueButton meeting! Note +that BigBlueButton will automatically end meetings that all users have left (after a minute or two). Thus if all users +have left a meeting, you will need to recreate the widget in order to spawn a new meeting. + +Created meetings are protected by a generated password that is included in the widget room state event. Thus one will +only be able to gain access to the meeting if they are in the room, or if someone in the room shares that information +with them. All users that join will have moderator permissions in the meeting, though this may change in the future to +allow meeting permissions based of room power level. + +### Troubleshooting + +This code was last tested with the [BigBlueButton v2.3 docker image](https://github.com/bigbluebutton/docker/). + +#### When using a Greenlight URL + +Let us know if you run into any problems! + +#### When having Dimension create meetings + +*My users are seeing 401 Unknown Session errors when trying to join a meeting!* + +BigBlueButton (or at least the [docker image](https://github.com/bigbluebutton/docker)) has a strange bug where +calling the [`/join`](https://docs.bigbluebutton.org/dev/api.html#join) API ends up failing to verify the session ID +*which it just passed to you*. There's discussion on the +issue [here](https://github.com/bigbluebutton/bigbluebutton/issues/6343) +and [here](https://groups.google.com/forum/#!topic/bigbluebutton-dev/TkjyUZP_gO8), but **TL;DR if you're getting +invalid session ID errors**, a workaround is to set `allowRequestsWithoutSession=true` +in `/usr/share/bbb-web/WEB-INF/classes/bigbluebutton.properties` (located in the `bbb-docker_bbb-web` container for +docker deployments). + +*I'm using the BigBlueButton docker image and it's taking about 20-30 seconds for a user to join a meeting. Why is it so slow?* + +This appears to be due to the BigBlueButton nginx container attempting to contact multiple html5-frontend instances, of +which you may only have configured one or two to start. nginx will wait for every request to timeout before returning +the result to yours though, hence the long wait. It's possible to edit the nginx configuration inside the containers to +remove the extra upstream directives and eliminate the timeout. But this is something that really needs to be fixed +upstream. + +*It sometimes says that my meeting does not exist! Where'd it go?* + +As mentioned above, BigBlueButton server will automatically remove meetings that everyone has left. Unfortunately we don't +currently have a way to remove the widget when this happens. Someone will permissions in the room will need to recreate +the widget and thus create a new meeting. \ No newline at end of file