Add BigBlueButton usage documentation
This commit is contained in:
Andrew Morgan
parent
85bcab3df7
commit
191f30819b
102
docs/bigbluebutton.md
Normal file
102
docs/bigbluebutton.md
Normal file
|
|
@ -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.
|
||||
Loading…
Reference in a new issue