Install

    From the user’s point of view, BigBlueButton is a virtual classroom for online teaching and learning. It was built for online learning, has a large community of teachers and developers that constantly work to improve it, and is deeply embedded into the world’s major learning management system. Users run BigBlueButton within their browsers with no additional software to install.

    From the administrator’s point of view, BigBlueButton web-based application. The BigBlueButton server runs a number of back-end processes to handle media, incoming API calls, processing of uploaded slides, and conversion of captured media into recordings. Administrators install BigBlueButton on a Ubuntu 18.04 64-bit server. This document shows you how to install.

    Before you install

    We recommend installing BigBlueButton with a ‘clean’ and dedicated Ubuntu 18.04 64-bit server with no prior software installed. If you want to upgrade from BigBlueButton 2.3, you can upgrade your existing server using the bbb-install.sh script and passing bionic-240 instead of bionic-230 as a repository. If you want to upgrade from BigBlueButton 2.2, we recommend setting up a clean server for BigBlueButton 2.4 and, after setup, migrate over your existing recordings.

    A ‘clean’ server does not have any previous web servers installed (such as apache) or web applications (such as plesk or webadmin) that are binding to port 80/443. By ‘dedicated’ we mean that this server won’t be used for anything else besides BigBlueButton (and possibly BigBlueButton-related applications such as Greenlight).

    Minimum server requirements

    For production, we recommend the following minimum requirements

    • Ubuntu 18.04 64-bit OS running Linux kernel 4.x
    • Latest version of docker installed
    • 16 GB of memory with swap enabled
    • 8 CPU cores, with high single-thread performance
    • 500 GB of free disk space (or more) for recordings, or 50GB if session recording is disabled on the server.
    • TCP ports 80 and 443 are accessible
    • UDP ports 16384 - 32768 are accessible
    • 250 Mbits/sec bandwidth (symmetrical) or more
    • TCP port 80 and 443 are not in use by another web server or reverse proxy
    • A hostname (such as bbb.example.com) for setup of a SSL certificate
    • IPV4 and IPV6 addres

    We also recommend installing on a bare metal server if possible. BigBlueButton uses FreeSWITCH for processing of incoming audio packets and FreeSWITCH works best in a non-virtualized environment (also see FreeSWITCH recommended configurations). Additonally, Kurento is used for routing audio-only streams and video streams.

    You can also install BigBlueButton on a virtualized environment or the cloud. For installing in virtual environments we recommend choosing a compute-intensive instance. For Amazon, choose a c5.2xlarge instance (or larger). On Digital Ocean we recommend the c-8 compute intensive instances (or larger). On Hetzner we recommend the AX51 servers or CCX32 instances.

    If you are setting up BigBlueButton for local development on your workstation, you can relax some of the above requirements as there will only be few users on the server. Starting with the above requirements, you can reduce them as follows

    • 4 CPU cores/8 GB of memory
    • Installation on a local VM container
    • 50G of disk space
    • IPV4 address only

    Regardless of your environment, you’ll need to setup a SSL certificate on the server. Why? For users to share audio/video from their computer, all browsers require a valid SSL certificate from the server to grant access to the user’s webcam or microphone via web real-time communications (WebRTC). If you try to access a BigBlueButton server with an IP address only, the browsers will block BigBlueButton client from accessing your webcam or microhone.

    Pre-installation checks

    Got a Ubuntu 18.04 64-bit server ready for installation? Great! But, before jumping into the installation section below, let’s do a few quick configuration checks to make sure your server meets the minimum requirements.

    Doning these checks will significantly reduce the chances you’ll hit a problem during installation.

    First, check that the locale of the server is en_US.UTF-8.

    $ cat /etc/default/locale
LANG="en_US.UTF-8"

    If you don’t see LANG="en_US.UTF-8", enter the following commands to set the local to en_US.UTF-8.

    $ sudo apt-get install -y language-pack-en
$ sudo update-locale LANG=en_US.UTF-8

    and then logout and login again to your SSH session – this will reload the locale configuration for your session. Run the above command cat /etc/default/locale again. Verify you see only the single line LANG="en_US.UTF-8".

    Note: If you see an additional line LC_ALL=en_US.UTF-8, then remove the entry for LC_ALL from /etc/default/locale and logout and then log back in once more.

    Next, do sudo systemctl show-environment and ensure you see LANG=en_US.UTF-8 in the output.

    $ sudo systemctl show-environment
LANG=en_US.UTF-8
PATH=/usr/local/sbin:/usr/local/bin:/usr/sbin:/usr/bin:/sbin:/bin

    If you don’t see this, do sudo systemctl set-environment LANG=en_US.UTF-8 and run the above sudo systemctl show-environment again and confirm you see LANG=en_US.UTF-8 in the output.

    Next, check that your server has (at lest) 16G of memory using the command free -h. Here’s the output from one of our test servers.

    $ free -h
              total        used        free      shared  buff/cache   available
Mem:            15G        3.1G        1.0G        305M         11G         12G
Swap:            0B          0B          0B

    Here it shows 15G of memory (that’s close enough as the server has 16 gigabytes of memory).

    If you see a value for Mem: in the total column less than 15G, then your server has insufficient memory to run BigBlueButton in production. You need to increase the server’s memory to (at least) 16G. (As stated above, if your running this in a development environment, 8G is fine.)

    Next, check that the server has Ubuntu is 18.04 as its operating system.

    $  cat /etc/lsb-release
DISTRIB_ID=Ubuntu
DISTRIB_RELEASE=18.04
DISTRIB_CODENAME=bionic
DISTRIB_DESCRIPTION="Ubuntu 18.04.5 LTS"

    Next, check that your server is running the 64-bit version of Ubuntu 18.04.

    $ uname -m
x86_64

    Next, check that your server supports IPV6.

    $ ip addr | grep inet6
inet6 ::1/128 scope host
...

    If you do not see the line inet6 ::1/128 scope host then after you install BigBlueButton you will need to modify the configuration for FreeSWITCH to disable support for IPV6.

    Next, check that your server is running Linux kernel 4.x.

    $ uname -r
4.15.0-NNN-generic

    Note: BigBlueButton will not run on a 2.6 Kernel (such as Linux 2.6.32-042stab133.2 on x86_64 on OpenVZ VPS).

    Next, check that your server has (at least) 8 CPU cores

    $ grep -c ^processor /proc/cpuinfo
8

    Sometimes we get asked “Why are you only supporting Ubuntu 18.04 64-bit?”. The answer is based on choosing quality over quantity. Long ago we concluded that its better for the project to have solid, well-tested, well-documented installation for a specific version of Linux that works really, really well than to try and support may variants of Linux and have none of them work well.

    At the moment, the requirement for docker may preclude running 2.4 within some virtualized environments, such as LXC and containerd; however, it ensures libreoffice runs within a restricted sandbox for document conversion. We are exploring if we can run libreoffice within systemd (such as systemd-nspawn).

    Install

    To install BigBlueButton, use bbb-install.sh script. (For previous versions we had step-by-step instructions; however, if you want to see all the steps done by bbb-install.sh, you can view its source code at bbb-install.sh.)

    The above link gives detailed information on using the script. As an example, the following command installs BigBlueButton 2.4 using hostname bbb.example.com and email address (for Let’s Encrypt) notice@example.com. It installs (or upgrades if the command is rerun later) the latest version of BigBlueButton 2.4 using -v bionic-240. It also installs the API demos (-a) and a firewall (-w).

    wget -qO- https://ubuntu.bigbluebutton.org/bbb-install.sh | bash -s -- -v bionic-240 -s bbb.example.com -e notice@example.com  -a -w

    Note: You can install Greenlight on the same server by also passing the -g option to bbb-install.sh.

    After the bbb-install.sh script finishes, you can check the status of your server with bbb-conf --check. When you run this command, you should see output similar to the following:

    $ sudo bbb-conf --check

BigBlueButton Server 2.4-rc-1 (2483)
                    Kernel version: 4.15.0-144-generic
                      Distribution: Ubuntu 18.04.6 LTS (64-bit)
                            Memory: 8167 MB
                         CPU cores: 4

/etc/bigbluebutton/bbb-web.properties (override for bbb-web)
/usr/share/bbb-web/WEB-INF/classes/bigbluebutton.properties (bbb-web)
       bigbluebutton.web.serverURL: https://test24.bigbluebutton.org
                defaultGuestPolicy: ALWAYS_ACCEPT
                 svgImagesRequired: true
              defaultMeetingLayout: SMART_LAYOUT

/etc/nginx/sites-available/bigbluebutton (nginx)
                       server_name: test24.bigbluebutton.org
                              port: 80, [::]:80
                              port: 443 ssl

/opt/freeswitch/etc/freeswitch/vars.xml (FreeSWITCH)
                       local_ip_v4: 138.197.139.2
                   external_rtp_ip: 138.197.139.2
                   external_sip_ip: 138.197.139.2

/opt/freeswitch/etc/freeswitch/sip_profiles/external.xml (FreeSWITCH)
                        ext-rtp-ip: $${local_ip_v4}
                        ext-sip-ip: $${local_ip_v4}
                        ws-binding: 138.197.139.2:5066
                       wss-binding: 138.197.139.2:7443

/usr/local/bigbluebutton/core/scripts/bigbluebutton.yml (record and playback)
                     playback_host: test24.bigbluebutton.org
                 playback_protocol: https
                            ffmpeg: 4.2.4-1ubuntu0.1bbb2~18.04

/etc/bigbluebutton/nginx/sip.nginx (sip.nginx)
                        proxy_pass: 138.197.139.2
                          protocol: http

/usr/local/bigbluebutton/bbb-webrtc-sfu/config/default.yml (Kurento SFU)
/etc/bigbluebutton/bbb-webrtc-sfu/production.yml (Kurento SFU - override)
                        kurento.ip: 138.197.139.2
                       kurento.url: ws://127.0.0.1:8888/kurento
                    kurento.sip_ip: 138.197.139.2
                    localIpAddress: 138.197.139.2
               recordScreenSharing: true
                     recordWebcams: true
                  codec_video_main: VP8
               codec_video_content: VP8

/usr/share/meteor/bundle/programs/server/assets/app/config/settings.yml (HTML5 client)
/etc/bigbluebutton/bbb-html5.yml (HTML5 client config override)
                             build: 2277
                        kurentoUrl: wss://test24.bigbluebutton.org/bbb-webrtc-sfu
                  enableListenOnly: true
                    sipjsHackViaWs: true




# Potential problems described below

# Warning: The API demos are installed and accessible from:
#
#    https://bbb.example.com
#
# and
#
#    https://bbb.example.com/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:
#
#    apt-get purge bbb-demo

    Any output that followed Potential problems may indicate configuration errors or installation errors. In many cases, the messages will give you recommendations on how to resolve the issue.

    You can also use sudo bbb-conf --status to check that all the BigBlueButton processes have started and are running.

    $ sudo bbb-conf --status
nginx —————————————————► [✔ - active]
freeswitch ————————————► [✔ - active]
redis-server ——————————► [✔ - active]
bbb-apps-akka —————————► [✔ - active]
bbb-fsesl-akka ————————► [✔ - active]
tomcat8 ———————————————► [✔ - active]
mongod ————————————————► [✔ - active]
bbb-html5 —————————————► [✔ - active]
bbb-webrtc-sfu ————————► [✔ - active]
kurento-media-server ——► [✔ - active]
bbb-html5-backend@1 ———► [✔ - active]
bbb-html5-backend@2 ———► [✔ - active]
bbb-html5-frontend@1 ——► [✔ - active]
bbb-html5-frontend@2 ——► [✔ - active]
etherpad ——————————————► [✔ - active]
bbb-web ———————————————► [✔ - active]

    You can also use dpkg -l | grep bbb- to list all the core BigBlueButton packages (your version numbers may be slightly different).

    # dpkg -l | grep bbb-

rc  bbb-activity-report       1:2.4.0-11     amd64  BigBlueButton bbb-activity-report
ii  bbb-apps-akka             2.4.0-48       all    BigBlueButton Apps (Akka)
ii  bbb-config                1:2.4.0-24     amd64  BigBlueButton configuration utilities
ii  bbb-demo                  1:2.4.0-2      amd64  BigBlueButton API demos
ii  bbb-etherpad              1:2.4.0-2      amd64  The EtherPad Lite components for BigBlueButton
ii  bbb-freeswitch-core       2:2.4.0-2      amd64  BigBlueButton build of FreeSWITCH
ii  bbb-freeswitch-sounds     1:1.6.7-1      amd64  FreeSWITCH Sounds
ii  bbb-fsesl-akka            2.4.0-16       all    BigBlueButton FS-ESL (Akka)
ii  bbb-html5                 1:2.4.0-2277   amd64  The HTML5 components for BigBlueButton
ii  bbb-learning-dashboard    1:2.4.0-6      amd64  BigBlueButton bbb-learning-dashboard
ii  bbb-libreoffice-docker    1:2.4.0-2      amd64  BigBlueButton setup for LibreOffice running in docker
ii  bbb-mkclean               1:0.8.7-1      amd64  Clean and optimize Matroska and WebM files
ii  bbb-playback              1:2.4.0-10     amd64  BigBlueButton playback
ii  bbb-playback-presentation 1:2.4.0-7      amd64  BigBluebutton playback of presentation
ii  bbb-record-core           1:2.4.0-8      amd64  BigBlueButton record and playback
ii  bbb-web                   1:2.4.0-38     amd64  BigBlueButton API
ii  bbb-webrtc-sfu            1:2.4.0-18     amd64  BigBlueButton WebRTC SFU

    With the API demos installed (that was the -a option), you can open https:/// in a browser (where is the hostname you specified in the `bbb-install.sh` command), enter your name, and click 'Join' to join 'Demo Meeting'. The BigBlueButton client should launch in 'Demo Meeting'.

    BigBlueButton Interface

    You can remove them with the command sudo apt-get purge bbb-demo.

    You can integrate BigBlueButton with one of the 3rd party integrations by providing the integration of the server’s address and shared secret. You can use bbb-conf to display this information using bbb-conf --secret.

    $ sudo bbb-conf --secret

      URL: https://bbb.example.com/bigbluebutton/
      Secret: 330a8b08c3b4c61533e1d0c334

      Link to the API-Mate:
      https://mconf.github.io/api-mate/#server=https://bbb.example.com/bigbluebutton/&sharedSecret=330a8b08c3b4c61533e1d0c334

    The link to API-Mate will open a page at https://mconf.github.io/api-mate/ and let you send valid API calls to your server. This makes it easy for testing wihthout the API demos.

    Configure the firewall (if required)

    Do you have a firewall between you and your users? If so, see configuring your firewall.

    Upgrading BigBlueButton 2.4

    You can upgrade by re-running the bbb-install.sh script again – it will download and install the latest release of BigBlueButton 2.4.

    Upgrading from BigBlueButton 2.2

    if you are upgrading BigBlueButton 2.2, we recommend setting up a new Ubuntu 18.04 server and transfer over the 2.2 recordings to the 2.4 server.

    Upgrading from BigBlueButton 2.3

    if you are upgrading BigBlueButton 2.3, you can simply re-run the bbb-install command you used for 2.3 but replacing the repository bionic-230 with bionic-240.

    After that, if the command sudo bbb-conf --check complains about a “Webhooks API Shared Secret mismatch”, reinstall the webhooks: sudo apt-get install --reinstall bbb-webhooks

    Restart your server

    You can restart and check your BigBlueButton server at any time using the commands

    $ sudo bbb-conf --restart
$ sudo bbb-conf --check

    The bbb-conf --check scans some of the log files for error messages. Again, any output that followed Potential problems may indicate configuration errors or installation errors. In many cases, the messages will give you recommendations on how to resolve the issue.

    If you see other warning messages check out the troubleshooting installation.

    Post installation steps

    If this server is intended for production, you should also

    We provide two publically accessible servers that you can use for testing:

    To learn more about integrating BigBlueButton with your application, check out the BigBlueButton API documentation. To see videos of BigBlueButton HTML5 client, see https://bigbluebutton.org/html5.

    Other installation options

    There are members of the community that provide other installation options for BigBlueButton.

    Ansible

    If you’re looking to deploy a large-scale installation of BBB using Scalelite then your servers are best managed using tools like Ansible. A few reasons you might go with this setup are:

    • easily customizable: your custom configurations will get replaced every time you upgrade automatically
    • parity across machines: ensure that you deploy the exact same version of BBB on every server
    • eliminate human error in setup: using bbb-install.sh or step-by-step methods are highly prone to human error as you can easily forget if you enabled a setting, chose to do X over Y, etc
    • automate to the fullest: by automating the process, you inherently save time on nasty troubleshooting and hours lost in manual configuration
    • easily scale at large: spin up an identical replica of your BBB server in less than 15 mins with no user input – preconfigured and ready to go

    Choose this method if you are already comfortable with a lot of the technical knowledge behind BigBlueButton, Scalelite and Greenlight/other front-ends. Refer to the following examples to create your installation.

    Note: These examples are not maintained or developed by the official BigBlueButton developers. These are entirely community-sourced, use at your own discretion.

    These first two install BigBlueButton on your server in a consistent fashion. You can specify variables, such as whether to install Greenlight too, what ports to use for TURN, and others. Functionally quite similar to bbb-install.sh but highly automated.

    Large scale deployments must include several other components in addition to the core BigBlueButton packages. These include Scalelite, Greenlight, a database, backups, nginx configurations, and more.

    Customizations

    Increase number of processes for nodejs

    See the HTML5 section on the Architecture page

    Increase number of recording workers

    Previous versions of BigBlueButton used a single thread for processing recordings. BigBlueButton 2.4 uses resque to spawn multiple recording workers for processing recordings.

    By default, /usr/lib/systemd/system/bbb-rap-resque-worker.service defines one recording worker Environment=COUNT=1.

    [Unit]
Description=BigBlueButton resque worker for recordings

[Service]
Type=simple
ExecStart=/bin/sh -c '/usr/bin/rake -f ../Rakefile resque:workers >> /var/log/bigbluebutton/bbb-rap-worker.log'
WorkingDirectory=/usr/local/bigbluebutton/core/scripts
Environment=QUEUE=rap:archive,rap:publish,rap:process,rap:sanity,rap:captions
Environment=COUNT=1
# Environment=VVERBOSE=1
User=bigbluebutton
Restart=always
RestartSec=3

[Install]
WantedBy=multi-user.target

    If you want 3 recording workers, for example, the steps below show how to add a systemd override file in /etc/systemd/system/bbb-rap-resque-worker.service.d/override.conf that sets Environment=COUNT=3 and restarts the bbb-rap-resque-worker.service service.

    Note: We have discovered an issue with having more than one worker present at a time if defaultKeepEvents or meetingKeepEvents in bbb-web is enabled. This is being currently addressed. For more information here is a link to the issue description.

    # mkdir -p /etc/systemd/system/bbb-rap-resque-worker.service.d
# cat > override.conf << HERE
[Service]
Environment=COUNT=3
HERE
# systemctl daemon-reload
# systemctl restart bbb-rap-resque-worker.service
# systemctl status bbb-rap-resque-worker.service
● bbb-rap-resque-worker.service - BigBlueButton resque worker for recordings
   Loaded: loaded (/usr/lib/systemd/system/bbb-rap-resque-worker.service; disabled; vendor preset: enabled)
  Drop-In: /etc/systemd/system/bbb-rap-resque-worker.service.d
           └─override.conf
   Active: active (running) since Sat 2021-01-09 12:19:22 UTC; 6s ago
 Main PID: 23630 (sh)
    Tasks: 15 (limit: 4915)
   CGroup: /system.slice/bbb-rap-resque-worker.service
      ├─23630 /bin/sh -c /usr/bin/rake -f ../Rakefile resque:workers >> /var/log/bigbluebutton/bbb-rap-worker.log
      ├─23631 /usr/bin/ruby /usr/bin/rake -f ../Rakefile resque:workers
      ├─23650 resque-2.0.0: Waiting for rap:archive,rap:publish,rap:process,rap:sanity,rap:captions
      ├─23651 resque-2.0.0: Waiting for rap:archive,rap:publish,rap:process,rap:sanity,rap:captions
      └─23652 resque-2.0.0: Waiting for rap:archive,rap:publish,rap:process,rap:sanity,rap:captions

    systemctl status bbb-rap-resque-worker.service shows three resque workers ready to process up to three recordings in parallel.

    The processing of recordings is also much faster thanks to the work of abatu in the community (see #2483).

    Run three Kurento servers

    Recommend running three parallel Kurento servers.

    Local overrides for configuration settings

    One challenge in maintaining a BigBlueButton 2.2 server was the packaging scripts would largely overwrite the settings files.

    The full description for local overrides for configuration files was moved to Administration -> Configuration Files

    Installing additional recording processing formats

    In addition to the presentation format that is installed and enabled by default, there are several optional recording formats available for BigBlueButton:

    • notes: Makes the shared notes from the meeting available as a document.
    • screenshare: Generate a single video file from the screensharing and meeting audio.
    • podcast: Generate an audio-only recording.

    The processing scripts and playback support files for these recording formats can be installed from the packages named bbb-playback-formatname (e.g. bbb-playback-notes)

    There is currently an issue where the recording formats are not automatically enabled when they are installed - see #12241 for details.

    In order to enable the recording formats manually, you need to edit the file /usr/local/bigbluebutton/core/scripts/bigbluebutton.yml. Look for the section named steps:. In this section, the recording processing workflow is defined, including what recording processing steps are performed, and what order they need to be performed in.

    To enable a new recording format, you need to add a new step named process:formatname that runs after the step named captions, and a new step named publish:formatname that runs after process:formatname. You may have to convert some of the steps to list format.

    For example, here are the stock steps in BigBlueButton 2.4 with the presentation format enabled:

    steps:
  archive: 'sanity'
  sanity: 'captions'
  captions: 'process:presentation'
  'process:presentation': 'publish:presentation'

    If you additionally enable the notes recording format, the steps will have to be changed to look like this:

    steps:
  archive: 'sanity'
  sanity: 'captions'
  captions:
    - 'process:presentation'
    - 'process:notes'
  'process:presentation': 'publish:presentation'
  'process:notes': 'publish:notes'

    This pattern can be repeated for additional recording formats. Note that it’s very important to put the step names containing a colon (:) in quotes.

    After you edit the configuration file, you must restart the recording processing queue: systemctl restart bbb-rap-resque-worker.service in order to pick up the changes.

    Troubleshooting

    Package locales-all is not available

    The package bbb-libreoffice needs to build a docker image for libreoffice. If you receive the following error when installing on a network behind a firewall

    Package locales-all is not available, but is referred to by another package.
This may mean that the package is missing, has been obsoleted, or
is only available from another source

E: Package 'locales-all' has no installation candidate
E: Unable to locate package libxt6
E: Unable to locate package libxrender1
The command '/bin/sh -c apt -y install locales-all fontconfig libxt6 libxrender1' returned a non-zero code: 100
dpkg: error processing package bbb-libreoffice-docker (--configure):
 installed bbb-libreoffice-docker package post-installation script subprocess returned error exit status 100

    Ubuntu 18.04 uses systemd-resolved, which presents a local caching resolver and registers this at /etc/resolv.conf. If you get they above error and have a local name server, such as 10.11.12.13, then try adding it with the hosts resolv.conf.

    echo "nameserver 10.11.12.13" > /etc/resolv.conf

    For more details see this issue.

    Feedback and reporting bugs

    If you found a reproducible bug, please report it in the GitHub Issues section with steps to reproduce (this will make it easier for the developers to fix the bug). Indicate in the body of the bug report that this applies to BigBlueButton 2.4 and give us the client build number, which you can find either with dpkg -l | grep bbb-html5 or within the client in the Settings -> About menu.