BigBlueButton in Docker

    This document describes how to run BigBlueButton 2.0-beta (or later) using Docker.

    The goal of creating a docker container for BigBlueButton was make it easy for anyone running docker to run BigBlueButton.

    In contrast, 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”.

    But for anyone with an operating system capable of running Docker, such as Mac OS X or Windows 10, they can now run a full BigBlueButton server with a single docker run command. Cool.

    Creating a docker image for BigBlueButton makes it very easy for any install, test, and try out BigBlueButton. Maybe your a WordPress developer or Moodle developer and want to try out BigBlueButton on your Max OS 10 computer. Now that’s easy to do. Maybe your a developer wanting to understand how BigBlueButton works. Now you can run a server, 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.

    Another design goal was to open just enough permissions to run BigBlueButton within docker – no more, no less. 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
    • Due to the overhead of mapping ports from the host to the container’s network, the default UDP port range for WebRTC is 38 ports (but this is configurable)
    • Processes are started using supervisord (instead of systemd)

    You can find the bigbluebutton/bigbluebutton Docker image on Docker hub.

    Installing Docker

    First, if you have not already done so, you need to install Docker on your computer. For instructions, see the Docker documentation.

    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

    It is recommended that you pull the latest image from Docker hub, but if you want to build the image yourself from source you should follow these steps. Otherwise, skip this 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, switch into the repo and execute the following command:

    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 conrtainer so it can listen for incoming connections. However, this IP address isn’t available to applications running within a 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/tcp -p 5066:5066/tcp -p 32730-32768:32730-32768/udp -p 2202:2202 --cap-add=NET_ADMIN --name bigbluebutton bigbluebutton/bigbluebutton -h 192.168.0.130
    

    If you didn’t already build the image, this may take a while to pull the image.

    The parameter --cap-add=NET_ADMIN gives the startup.sh script the ability to setup a dummy network interface card (NIC) to enable FreeSWITCH to bind to the host’s IP address for receiving the RTP stream for a WebRTC audio connection.

    A few more words on startup.sh – this script makes all the necessary modifications to BigBlueButton’s configuration files before running supervisord (which starts up all the BigBlueButton components).

    BigBlueButton takes about 10 seconds to startup. After that, you can login with FireFox using http://<HOSTIP> and launch BigBlueButton.

    Install

    The Docker image installs the package bbb-demo 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

    Administration

    Login to the container

    You can directly login to the running container. To login to the container, execute 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-beta (703)
                        Kernel version: 4.4.0-83-generic
                          Distribution: Ubuntu 16.04.3 LTS (64-bit)
                                Memory: 32839 MB
    
    /var/www/bigbluebutton/client/conf/config.xml (bbb-client)
                    Port test (tunnel): 192.168.0.130
                                  red5: 192.168.0.130
                  useWebrtcIfAvailable: true
    
    /opt/freeswitch/etc/freeswitch/sip_profiles/external.xml (FreeSWITCH)
                        websocket port:     <param name=
                        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
    
    
    ** 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 setting of 192.168.0.130 for proxy_pass in
    #
    #    /etc/bigbluebutton/nginx/sip.nginx
    #
    # does not match the local IP address (172.17.0.2).
    # (This is OK if you've manually changed the values)
    
    # Warning: The setting of  for local_ip_v4 in
    #
    #    /opt/freeswitch/etc/freeswitch/vars.xml
    #
    # does not match the local IP address (172.17.0.2).
    # (This is OK if you've manually changed the values)
    
    # 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 whereas the IP address of the host is 192.168.0.130. There is a warning about a missmatch, but that’s because Docker assigns each container it’s own IP address.

    # ifconfig
    eth0      Link encap:Ethernet  HWaddr 02:42:ac:11:00:02
              inet addr:172.17.0.2  Bcast:0.0.0.0  Mask:255.255.0.0
              UP BROADCAST RUNNING MULTICAST  MTU:1500  Metric:1
              RX packets:8 errors:0 dropped:0 overruns:0 frame:0
              TX packets:2 errors:0 dropped:0 overruns:0 carrier:0
              collisions:0 txqueuelen:0
              RX bytes:648 (648.0 B)  TX bytes:108 (108.0 B)
    
    lo        Link encap:Local Loopback
              inet addr:127.0.0.1  Mask:255.0.0.0
              UP LOOPBACK RUNNING  MTU:65536  Metric:1
              RX packets:699 errors:0 dropped:0 overruns:0 frame:0
              TX packets:699 errors:0 dropped:0 overruns:0 carrier:0
              collisions:0 txqueuelen:1
              RX bytes:218932 (218.9 KB)  TX bytes:218932 (218.9 KB)
    

    You can now view BigBlueButton’s log files and restart BigBlueButton (see next section). On some systems, we noticed that the aboe

    Restart BigBlueButton

    The Ubuntu 16.04 image for Docker does not provide systemd. To start all the individual BigBlueButton components that would normally be run with systemd, the docker container 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 144, uptime 0:01:57
    bbb-fsesl-akka                   RUNNING   pid 139, uptime 0:01:57
    bbb-html5                        RUNNING   pid 151, uptime 0:01:57
    freeswitch                       RUNNING   pid 147, uptime 0:01:57
    mongod                           RUNNING   pid 136, uptime 0:01:57
    nginx                            RUNNING   pid 143, uptime 0:01:57
    rap-archive-worker               RUNNING   pid 1651, uptime 0:00:13
    rap-process-worker               RUNNING   pid 1653, uptime 0:00:12
    rap-publish-worker               RUNNING   pid 1649, uptime 0:00:14
    rap-sanity-worker                RUNNING   pid 1655, uptime 0:00:10
    red5                             RUNNING   pid 137, uptime 0:01:57
    redis-server                     EXITED    Oct 24 11:48 PM
    tomcat7                          RUNNING   pid 135, uptime 0:01:57
    

    Yo may see record and playback scripts showing EXITED. This is the expected behaviour (they automatically quit after 30 seconds if there is no recording to process) an supervisord` will simply run them again.

    You can restart BigBlueButton using the command supervisorctl restart all

    # supervisorctl restart all
    nginx: stopped
    libreoffice: stopped
    bbb-apps-akka: stopped
    bbb-fsesl-akka: stopped
    tomcat7: stopped
    red5: stopped
    freeswitch: stopped
    red5: started
    bbb-fsesl-akka: started
    tomcat7: started
    nginx: started
    bbb-apps-akka: started
    freeswitch: started
    redis-server: started
    libreoffice: started
    bbb-rap-publish-worker: ERROR (spawn error)
    rap-sanity-worker: ERROR (spawn error)
    rap-process-worker: ERROR (spawn error)
    rap-archive-worker: ERROR (spawn error)
    

    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.