cloud_bbb/README.md

174 lines
8.4 KiB
Markdown
Raw Normal View History

2020-04-26 11:36:41 +02:00
# BigBlueButton™ integration for Nextcloud
2021-02-13 18:48:21 +01:00
![Static analysis](https://github.com/sualko/cloud_bbb/workflows/Static%20analysis/badge.svg)
![PHP Tests](https://github.com/sualko/cloud_bbb/workflows/PHP%20Tests/badge.svg)
![Lint](https://github.com/sualko/cloud_bbb/workflows/Lint/badge.svg)
2020-04-29 12:03:40 +02:00
![Downloads](https://img.shields.io/github/downloads/sualko/cloud_bbb/total.svg)
![GitHub release](https://img.shields.io/github/release/sualko/cloud_bbb.svg)
2020-06-18 16:03:16 +02:00
2020-06-18 11:11:40 +02:00
[![ko-fi](https://www.ko-fi.com/img/githubbutton_sm.svg)](https://ko-fi.com/sualko)
2020-04-29 12:03:40 +02:00
This app allows to create meetings with an external installation of [BigBlueButton](https://bigbluebutton.org).
:clap: Developer wanted! If you have time it would be awesome if you could help to enhance this application.
__This app uses BigBlueButton and is not endorsed or certified by BigBlueButton Inc. BigBlueButton and the BigBlueButton Logo are trademarks of BigBlueButton Inc.__
2020-04-30 09:54:25 +02:00
![Screenshot configuration](https://github.com/sualko/cloud_bbb/raw/master/docs/screenshot-configuration.png)
2020-04-29 12:03:40 +02:00
## :heart_eyes: Features
This integration provides the following features:
* **Room setup** Create multiple room configurations with name, welcome message, ...
* **Share guest link** Share the room link with all your guests
2020-09-01 10:03:40 +02:00
* **Share rooms** Share rooms with members, groups or circles
2020-04-29 12:03:40 +02:00
* **Custom presentation** Start a room with a selected presentation from your file browser
2020-05-17 12:07:24 +02:00
* **Manage recordings** View, share and delete recordings for your rooms
2020-09-01 10:03:40 +02:00
* **Restrictions** Restrict room creation to certain groups
2020-09-24 14:19:54 +02:00
* **Activities** Get an overview of your room activities
2020-04-29 12:03:40 +02:00
## :rocket: Install it
The easiest way to install this app is by using the [Nextcloud app store](https://apps.nextcloud.com/apps/bbb).
If you like to build from source, please continue reading.
2020-04-26 11:36:41 +02:00
To install it change into your Nextcloud's apps directory:
cd nextcloud/apps
Then run:
2020-04-26 13:26:34 +02:00
git clone https://github.com/sualko/cloud_bbb.git bbb
2020-04-26 11:36:41 +02:00
Then install the dependencies using:
make build
2020-04-29 12:03:40 +02:00
## :gear: Configure it
2020-04-29 12:12:15 +02:00
Get your BBB API url and secret by executing `sudo bbb-conf --secret` on your
BBB server.
2020-04-29 12:12:15 +02:00
```
$ sudo bbb-conf --secret
URL: https://bbb.your.domain/bigbluebutton/
Secret: abcdefghijklmnopqrstuvwxyz012345679
Link to the API-Mate:
https://mconf.github.io/api-mate/#server=https://...
```
Enter these values in the additional settings section on the admin
configuration page of your Nextcloud instance.
2021-02-13 19:20:26 +01:00
![Screenshot admin section](https://github.com/sualko/cloud_bbb/raw/master/docs/screenshot-admin.png)
### Manual configuration (for experts)
If you prefer not to use the web interface for configuration, you will find all
used configuration keys in the list below. Please beware that there will be no
check if those values are correct. Therefore this is not the recommended way.
The syntax to set all settings is `occ config:app:set bbb KEY --value "VALUE"`.
Key | Description
--------------------------------- | ------------------------------------------------------------------------------------
`app.navigation` | Set to `true` to show navigation entry
`app.navigation.name` | Defines the navigation label. Default "BigBlueButton".
`api.url` | URL to your BBB server. Should start with `https://`
`api.secret` | Secret of your BBB server
`api.meta_analytics-callback-url` | URL which gets called after meetings ends to generate statistics. See [bbb-analytics](https://github.com/betagouv/bbb-analytics).
`app.shortener` | Value of your shortener service. Should start with `https://` and contain `{token}`.
`avatar.path` | Absolute path to an optional avatar cache directory.
`avatar.url` | URL which serves `avatar.path` to be used as avatar cache.
2022-01-05 09:59:49 +01:00
### Avatar cache (v2.2+)
The generation of avatars puts a high load on your Nextcloud instance, since the
number of requests increases squarely to the number of participants in a room.
To mitigate this situation, this app provides an optional avatar file cache. To
activate the cache `avatar.path` and `avatar.url` have to be configured.
`avatar.path` must provide an absolute path (e.g. `/srv/bbb-avatar-cache/`) to a
directory which is writable by the PHP user. `avatar.url` must contain the url
which serves all files from `avatar.path`. To bypass browser connection limits
we recommend to setup a dedicated host.
Example Apache configuration for a dedicated host with `avatar.path = /srv/bbb-avatar-cache/`
and `avatar.url = https://avatar-cache.your-nextcloud.com/`:
```
<VirtualHost *:443>
ServerName avatar-cache.your-nextcloud.com
Header always set Strict-Transport-Security "max-age=15768000;"
DocumentRoot /srv/bbb-avatar-cache
<Directory /srv/bbb-avatar-cache>
Options -FollowSymLinks -Indexes
</Directory>
SSLEngine On
# SSL config...
</VirtualHost>
```
For additional security, we recommend to disable directory listing, symlinks and
any language interpreter such as php for the cache directory.
Cached avatars are usually deleted as soon as the meeting ends. In cases the BBB
server shuts down unexpected, we provide the `bbb:clear-avatar-cache` occ
command (example use: `./occ bbb:clear-avatar-cache`).
## :bowtie: User guide
### Create your first room
2020-04-29 12:12:15 +02:00
Go to the BigBlueButton section inside your personal settings page and enter a
2020-04-29 12:03:40 +02:00
room name. That's it. You can now distribute the room url.
### Enter a room from files
2020-04-29 12:03:40 +02:00
Use the ... menu and select the desired BBB configuration to enter the room.
Beware that if the room is already running the presentation will **not** be
2020-04-30 09:54:25 +02:00
updated. Entering a room with a defined presentation works only if link shares
are enabled and do not require authentication. See [#1](https://github.com/sualko/cloud_bbb/issues/1)
for details.
2020-04-29 12:03:40 +02:00
![Screenshot file browser](https://github.com/sualko/cloud_bbb/raw/master/docs/screenshot-file-browser.png)
2020-05-17 12:07:24 +02:00
## :notebook: Notes
2020-05-17 12:04:35 +02:00
- By using the [Link Editor](https://apps.nextcloud.com/apps/files_linkeditor)
2020-04-30 09:54:25 +02:00
you can share rooms as any other file
2020-05-17 12:07:24 +02:00
## :pick: Troubleshooting
2020-04-30 09:54:25 +02:00
- Before installing, make sure your BBB is running correctly
- If the room doesn't appear in the ... menu of files, a browser/cache reload
2020-04-29 12:03:40 +02:00
might help
- To share an audio (mp3) or video (mp4) file with your audience follow these steps (more info in [#148](https://github.com/sualko/cloud_bbb/issues/148#issuecomment-827338650)):
- create a public share of the exact file
- copy the location of the share from the share information screen into your clipboard
- open big blue button, press the plus icon in the lower left corner
- click on add external video
- paste the url from your clipboard and append the following string for audio `/download?.mp3` or `/download?.mp4` for video files
2021-05-18 08:50:32 +02:00
- To connect to a ScaleLite server, use the url like `https://yourscalelite.url/bigbluebutton/` without additional `api/` and as secret ScaleLite's `LOADBALANCER_SECRET`
2020-05-17 12:04:35 +02:00
2020-05-17 12:07:24 +02:00
## :heart: Sponsors
2020-05-17 12:04:35 +02:00
Writing such an application is a lot of work and therefore we are specially
thankful for people and organisations who are sponsoring features or bug fixes:
- [Medienwerkstatt Minden-Lübbecke e.V.](https://www.medienwerkstatt.org) manage recordings ([#19])
2020-06-18 16:03:16 +02:00
- [Deutscher Bundesjugendring](https://www.dbjr.de) version [0.4.0], version [0.5.0]
2020-08-29 14:53:11 +02:00
- [Graz University of Technology](https://www.tugraz.at) form action ([#47]), navigation entry ([#31]), restrictions ([#43], [#53]), circles ([#61])
2021-01-27 15:16:47 +01:00
- [Arawa](https://www.arawa.fr) UX audit
- [Niedersächsisches Landesinstitut für schulische Qualitätsentwicklung Netzwerk Medienberatung](https://nlq.niedersachsen.de/) moderator url, UX improvements
2021-04-19 14:49:20 +02:00
- [Integrierte Gesamtschule Lengede](http://www.igs-lengede.de/) theme, join options
2020-05-17 12:04:35 +02:00
If you are looking for other ways to contribute to this project, you are welcome
to look at our [contributor guidelines]. Every contribution is valuable :tada:.
[contributor guidelines]: https://github.com/sualko/cloud_bbb/blob/master/.github/contributing.md
2020-06-10 17:27:10 +02:00
[#19]: https://github.com/sualko/cloud_bbb/issues/19
2020-08-29 14:53:11 +02:00
[#47]: https://github.com/sualko/cloud_bbb/issues/47
[#31]: https://github.com/sualko/cloud_bbb/issues/31
[#43]: https://github.com/sualko/cloud_bbb/issues/43
[#53]: https://github.com/sualko/cloud_bbb/issues/53
[#61]: https://github.com/sualko/cloud_bbb/issues/61
2020-06-18 16:03:16 +02:00
[0.4.0]: https://github.com/sualko/cloud_bbb/releases/tag/v0.4.0
[0.5.0]: https://github.com/sualko/cloud_bbb/releases/tag/v0.5.0