BigBlueButton runs within Docker
This document describes how to run a BigBlueButton 2.0 (or later) server inside a docker container. Running BigBlueButton inside of Docker makes it easy for anyone to try BigBlueButton on their computer (instead of getting a remote server).
However, if you have a computer (such as Mac OS X) that runs Docker, you can obtain the IP address of your computer (using
ifconfig) and then run BigBlueButton server with a single command.
docker run -p 80:80/tcp -p 443:443/tcp -p 1935:1935 -p 5066:5066 -p 3478:3478 -p 3478:3478/udp bigbluebutton/bigbluebutton -h IP_ADDRESS
We were not trying to create a production version of BigBlueButton that runs under docker. If you look at the Docker file for BigBlueButton, you’ll see it runs everything within a single container. This is clearly not the “docker way”.
Still, for anyone curious to try out BigBlueButton on a operating system capable of running Docker you now run your own BigBlueButton server with a single
docker run command. Maybe your a WordPress developer or Moodle developer and want to try out BigBlueButton with your site, or maybe your a developer wanting to understand how BigBlueButton works. Now you can run a server locally, SSH into it, see how it works, make changes (and maybe even break a few things to understand more), and then wipe the slate clean and start again. Cool.
Another goal of creating a Docker container for BigBlueButton was to explore how far we could go without requiring any elevated previliges to run. In other words, we wanted BigBlueButton running within docker to be isolated from the host computer and minimized resource conflicts.
As a result, running BigBlueButton in Docker has the following limitations:
- Nginx does not have a SSL certificate, so you’ll need to use FireFox to use WebRTC audio/video
- Processes are started using
- The HTML5 client supports video but not desktop sharing using WebRTC
You can find the lateset Docker image on Docker hub at bigbluebutton/bigbluebutton
You need to install Docker on your computer. The docker site has very good instructions for installation.
Running BigBlueButton in Docker
You have two options for running BigBlueButton in Docker. You can either pull the image from Docker hub or build the Docker image from source.
Build the Docker Image
If you want to build the Docker image yourself from source, do the following steps; otherwise, skip to the next section.
You will need to clone the source from Github. You can find the repository on Github at bigbluebutton/docker.
git clone https://github.com/bigbluebutton/docker
If you have a local
apt-get caching server (such as using
apt-cacher-ng), then edit the Docker file, uncomment the following line and change 192.168.0.130 to match the hostname/IP address of your proxy server.
# RUN echo 'Acquire::http::Proxy "http://192.168.0.130:3142";' > /etc/apt/apt.conf.d/01proxy
Doing this will speed up repeated builds of the Docker container.
To build the docker image, enter the directory and run the following
docker build command:
cd docker docker build -t bigbluebutton/bigbluebutton .
After Docker has finished building the BigBlueButton image, you can check it using the
docker images command.
$ docker images REPOSITORY TAG IMAGE ID CREATED SIZE bigbluebutton/bigbluebutton latest ca5ab0317d11 18 hours ago 3.11 GB
Run BigBlueButton in Docker
BigBlueButton needs to know the IP address of the host running the container so it can listen for incoming connections. However, Docker does not make the host’s IP address available to applications running within inside a docker container. Therefore, to run BigBlueButton witin a Docker container, you need to pass the IP address of your computer via the parameter
-h <HOSTIP>. Here we are running BigBlueButton on the host with IP address
docker run -p 80:80/tcp -p 1935:1935 -p 5066:5066 -p 3478:3478 -p 3478:3478/udp --name bigbluebutton bigbluebutton/bigbluebutton -h 192.168.0.130
If you didn’t already build the image, it will take a few minutes to pull the image from Docker Hub. Once the docker container is running, takes a few more seconds for BigBlueButton to startup. Once started, you can login with FireFox using
http://<HOSTIP> and launch BigBlueButton.
The Docker image has the package
bbb-demo already installed so all the API demos are available. You can access the HTML5 client with the
http://<HOSTIP>/demo/demoHTML5.jsp. Here’s the HTML5 client running within the docker container.
Under the hood
The installation of BigBlueButton occurs using the standard BigBlueButton packages. You can see this in the Dockerfile at the step
RUN apt-get install -y bigbluebutton
However, Docker is designed to run a single process. Normally, BigBlueButton would use
systemd to start/stop all the processes. However, Docker does not support
systemd. We took inspiration from this project that runs Canvas LMS inside using
supervisorctl to start the processes.
The end of the Docker file for BigBlueButton runs a script
ADD setup.sh /root/setup.sh ENTRYPOINT ["/root/setup.sh"] CMD 
which receives the parameter
-h IP for the IP address of your computer. It then updates all the BigBlueButton configuration files to use that
IP address, and at the end runs
supervisorctl to start the individual BigBlueButton components.
exec /usr/bin/supervisord > /var/log/supervisord.log
supervisorctl runs, it uses the supervisord.conf file to run each of the processes
Both FreeSWITCH and Kurento (installed by
bbb-webrtc-sfu) are listening to the internal IP address of the Docker container. The TURN server
coturn proxies all the external request for web socket connections to FreeSWITCH and Kurento through port 3478. The Record and Playback (rap) workers get run every 20 seconds by
Login to the container
If the container is running, you can login using the command
$ docker exec -it bigbluebutton /bin/bash root@4dd41ad9bba0:/#
Yay, we now have a full BigBlueButton server at our command. Let’s see what
bbb-conf --check says.
BigBlueButton Server 2.0.0-RC5 (1547) Kernel version: 4.4.0-109-generic Distribution: Ubuntu 16.04.5 LTS (64-bit) Memory: 16394 MB /var/www/bigbluebutton/client/conf/config.xml (bbb-client) Port test (tunnel): rtmp://192.168.0.130 red5: 192.168.0.130 useWebrtcIfAvailable: true /opt/freeswitch/etc/freeswitch/sip_profiles/external.xml (FreeSWITCH) websocket: :5066 WebRTC enabled: true /etc/nginx/sites-available/bigbluebutton (nginx) server name: 192.168.0.130 port: 80, [::]:80 bbb-client dir: /var/www/bigbluebutton /var/lib/tomcat7/webapps/bigbluebutton/WEB-INF/classes/bigbluebutton.properties (bbb-web) bbb-web host: 192.168.0.130 /var/lib/tomcat7/webapps/demo/bbb_api_conf.jsp (API demos) url: 192.168.0.130 /usr/share/red5/webapps/bigbluebutton/WEB-INF/red5-web.xml (red5) voice conference: FreeSWITCH /usr/local/bigbluebutton/core/scripts/bigbluebutton.yml (record and playback) playback host:192.168.0.130 ffmpeg: 4.0.2-1~16.04.york0.1 /usr/local/bigbluebutton/bbb-webrtc-sfu/config/default.yml (Kurento) kurentoUrl: ws://172.17.0.2:8888/kurento kurentoIp: 172.17.0.2 localIpAddress: 172.17.0.2 recordScreenSharing: true recordWebcams: true Node: v8.11.4 mongoDB: v3.4.16 ** Potential problems described below ** # IP does not match: # IP from ifconfig: 172.17.0.2 # /etc/nginx/sites-available/bigbluebutton: 192.168.0.130 # Warning: API URL IPs do not match host: # # IP from ifconfig: 172.17.0.2 # /var/lib/tomcat7/webapps/demo/bbb_api_conf.jsp: 192.168.0.130 # Warning: The API demos are installed and accessible from: # # http://192.168.0.130/demo/demo1.jsp # # These API demos allow anyone to access your server without authentication # to create/manage meetings and recordings. They are for testing purposes only. # If you are running a production system, remove them by running: # # sudo apt-get purge bbb-demo
Here you can see the internal IP address of the docker container is 172.17.0.2 does not match the external IP address of the host is 192.168.0.130. This is more of a warning as the
setup.sh script has already configured BigBlueButton with an internal/external IP address according to the steps to configure BigBlueButton behind a firewall.
As stated ealier, the Ubuntu 16.04 image for Docker does not provide
systemd but instead uses supervisord.
To see the status of all the processes, login to the Docker container (see previous section) and enter the command
# supervisorctl status bbb-apps-akka RUNNING pid 145, uptime 0:05:38 bbb-fsesl-akka RUNNING pid 139, uptime 0:05:38 bbb-html5 RUNNING pid 162, uptime 0:05:38 bbb-webrtc-sfu RUNNING pid 158, uptime 0:05:38 coturn RUNNING pid 165, uptime 0:05:38 freeswitch RUNNING pid 148, uptime 0:05:38 kurento-media-server RUNNING pid 146, uptime 0:05:38 mongod RUNNING pid 478, uptime 0:05:37 nginx RUNNING pid 143, uptime 0:05:38 rap-archive-worker RUNNING pid 1716, uptime 0:00:04 rap-process-worker RUNNING pid 1718, uptime 0:00:03 rap-publish-worker STARTING rap-sanity-worker RUNNING pid 1720, uptime 0:00:01 red5 RUNNING pid 136, uptime 0:05:38 redis-server EXITED Aug 31 02:59 PM tomcat7 RUNNING pid 138, uptime 0:05:38
You may see record and playback scripts showing
EXITED. This is the expected behaviour as they automatically quit after 20 seconds if there is no recording to process) and supervisord` will simply run them again.
You can restart BigBlueButton using the command
supervisorctl restart all
# supervisorctl restart all rap-archive-worker: stopped rap-publish-worker: stopped bbb-html5: stopped coturn: stopped rap-process-worker: stopped rap-sanity-worker: stopped nginx: stopped kurento-media-server: stopped bbb-webrtc-sfu: stopped mongod: stopped bbb-apps-akka: stopped bbb-fsesl-akka: stopped red5: stopped tomcat7: stopped freeswitch: stopped red5: started tomcat7: started bbb-fsesl-akka: started nginx: started bbb-apps-akka: started freeswitch: started redis-server: started coturn: started mongod: ERROR (spawn error) rap-archive-worker: started rap-process-worker: started rap-sanity-worker: started rap-publish-worker: started kurento-media-server: started bbb-webrtc-sfu: started bbb-html5: started
Again, you can ignore the
(spawn error) for the record and playback scripts as they exit if there is not recording to process.
Stopping to docker container
When you are finished with running BigBlueButton in docker, get the name of the container with
docker ps. For example, if this command returns the name of the container as
vibrant_shockley, then you can stop the container with the command
# docker stop bigbluebutton
Windows 10 Pro automatically binds to port 80
We not yet figured out how to run BigBlueButton on Windows 10 pro as Windows seems to already have an application binding to port 80.