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).

    If you have an external server that meets the following minimal requirements, you can install BigBlueButton following the step-by-step instructions or with a single command using bbb-install.sh.

    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 supervisord (instead of systemd)
    • The HTML5 client supports video but not desktop sharing using WebRTC

    You can find the lateset Docker image on Docker hub at bigbluebutton/bigbluebutton

    Getting Started

    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 192.168.0.130.

    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.

    Install

    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.

    Install

    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 startup.sh

    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
    

    When supervisorctl runs, it uses the supervisord.conf file to run each of the processes

    • bbb-apps-akka
    • bbb-fsesl-akka
    • bbb-html5
    • bbb-webrtc-sfu
    • coturn
    • freeswitch
    • kurento-media-server
    • mongod
    • nginx
    • rap-archive-worker
    • rap-process-worker
    • rap-publish-worker
    • rap-sanity-worker
    • red5
    • redis-server
    • tomcat7

    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 supervisorctl.

    Administration

    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.

    Restart BigBlueButton

    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.

    # 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
    

    Troubleshooting

    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.