mirror of
https://github.com/turt2live/matrix-dimension.git
synced 2024-07-08 20:11:48 +00:00
Add BigBlueButton usage documentation
This commit is contained in:
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 New Issue
Block a user