Welcome to the BigBlueButton Developer’s Guide for BigBlueButton 2.2.
This document gives you an overview of how to setup a development environment for BigBlueButton 2.2.
Before you begin
You first need to setup a BigBlueButton 2.2 server. See the instructions at Install BigBlueButton 2.2.
A BigBlueButton server is built from a number of components that correspond to Ubuntu packages. Some of these components are
- bbb-web – Implements the BigBlueButton API and conversion of documents for presentation
- akka-bbb-apps – Server side application that handles the state of meetings on the server
- bbb-html5 – HTML5 client that loads in the browser. The client server-side meteor application that leverages MongoDB and React.js
- bbb-fsesl-akka – Component to send commands to FreeSWITCH
- bbb-playback-presentation – Record and playback script to create presentation layout
- bbb-webrtc-sfu – Server that bridges incoming requests from client to Kurento
- kurento-media-server – WebRTC media server for sending/receiving/recording video (webcam and screen share)
- bbb-freeswitch-core – WebRTC media server for sending/receiving/recording audio
This document describes how to setup a development environment using an existing BigBlueButton 2.2 server. Once the environment is setup, you will be able to make custom changes to BigBlueButton source, compile the source, and replace the corresponding components on the server (such as updating the BigBlueButton client).
The instructions in this guide are step-by-step so you can understand each step needed to modify a component. If you encounter problems or errors at any section, don’t ignore the errors. Stop and double-check that you have done the step correctly. If you are unable to determine the cause of the error, do the following
- First, use Google to search for the error. There is a wealth of information in bigbluebutton-dev that has been indexed by Google.
- Try doing the same steps on a different BigBlueButton server.
- Post a question to bigbluebutton-dev with a description of the problem and the steps to reproduce. Post logs and error messages to Pastebin link them in your post.
Before you begin
This section makes sure you are ready to setup a BigBlueButton development environment.
You Have a Working BigBlueButton Server
Before you can start developing on BigBlueButton, you must install BigBlueButton 2.2 (see installation steps) and ensure it’s working correctly. Make sure there were no errors during the installation and that you can join a session successfully.
We emphasize that your BigBlueButton server must be working before you start setting up the development environment. Be sure that you can login, start sessions, join the audio bridge, share your webcam, and record and playback sessions – all using the built-in API demos.
By starting with a working BigBlueButton server, you have the ability to switch back-and-forth between the default-packaged components and any modifications you make.
For example, suppose you modify the BigBlueButton client and something isn’t working (such as the client is not fully loading), you can easily switch back to the default-packaged client and check that it’s working correctly (thus ruling out any environment issues that may also be preventing your modified client from loading).
Another Note: These instructions assume you have the
bbb-demo package installed so you can run any of the API demos to test your setup.
Developing on Windows
To develop BigBlueButton from within Windows, you have two options:
- use Windows Subsystem for Linux
- use VMWare Player or VirtualBox to create a virtual machine (VM).
Choose the OS to be Ubuntu 16.04 64-bit. The associated documentation for VMWare Player and VirtualBox or WSL will guide you on setting up a new 16.04 64-bit VM.
Note: When setting up the VM, it does not matter to BigBlueButton if you setup Ubuntu 16.04 server or desktop. If you install desktop, you’ll have the option of using a graphical interface to edit files. When running the VM, you will need a host operating system capable of running a 64-bit virtual machine.
Important: Make sure you create another user such as “ubuntu” to avoid running into permission errors such as Nginx 403 Forbidden error or error-null-while-compiling-resource-bundles-under-linux-with-hudson.
Do not run commands as the root user and only use sudo when instructed to.
These instructions are written for an account called “ubuntu”, but they will apply to any account that has the permissions to execute commands as root, such as
You’ll need to download some files throughout these instructions using wget. If it’s not installed on your server, you can install the package using the following command
sudo apt-get install wget
Have a GitHub Account
The BigBlueButton source is hosted on GitHub. You need a GitHub account. In addition, you need to be very familiar with how git works. Specifically, you need to know how to
- clone a repository
- create a branch
- push changes back to a repository
If you have not used git before, or if the terms clone, branch, and commit are unfamiliar to you, stop now. These are fundamental concepts to git that you need to become competent with before trying to develop on BigBlueButton. To become competent, a good place to start is this free book and GitHub Help pages.
Using GitHub makes it easy for you to work on your own copy of the BigBlueButton source, store your updates to the source to your GitHub account, and make it easy for you to contribute to BigBlueButton.
Subscribe to bigbluebutton-dev
We recommend you subscribe to the bigbluebutton-dev mailing list to follow updates to the development of BigBlueButton and to collaborate with other developers.
Setup a Development Environment
First, you need to install the core development tools.
sudo apt-get install git-core ant ant-contrib openjdk-8-jdk-headless
With the JDK installed, you need to set the JAVA_HOME variable. Edit
~/.profile (here we are using vim to edit the file)
Add the following line at the end of the file
Reload your profile (this will happen automatically when you next login, but we’ll do it explicitly here to load the new environment variable).
Do a quick test to ensure JAVA_HOME is set.
$ echo $JAVA_HOME /usr/lib/jvm/java-8-openjdk-amd64
In the next step, you need to install a number of tools using sdkman.
curl -s "https://get.sdkman.io" | bash source "$HOME/.sdkman/bin/sdkman-init.sh" sdk install gradle 5.5.1 sdk install grails 3.3.9 sdk install sbt 1.2.8 sdk install maven 3.5.0
Instructions for downloading the Flash SDK can be found here.
Checking out the Source
With the development tools installed, we’ll next clone the source in the following directory:
Using your GitHub account, do the following
- Fork the BigBlueButton repository into your GitHub account
- Clone your repository into your
After cloning, you’ll have the following directory (make sure the
bigbluebutton directory is within your
Confirm that you are working on the
cd /home/ubuntu/dev/bigbluebutton git status
You should see
On branch v2.2.x-release Your branch is up-to-date with 'origin/v2.2.x-release'. nothing to commit, working directory clean
When you first clone the BigBlueButton git repository, git will place you, by default, on the
master branch, which is the latest code for BigBlueButton. Earlier, the
master branch is fine for BBB 2.2 development, but the development for 2.2 now occurs on the release branch named
The first thing we need to do is to add the remote repository to our local clone.
git remote add upstream https://github.com/bigbluebutton/bigbluebutton.git
You can now check your local list of tracked repositories to verify that the addition worked. You should see at least two results (origin and upstream). The one named “origin” should link to your personal fork and is the repository that you cloned. The second result “upstream” should link to the main BigBlueButton repository.
git remote -v
After, we need to fetch the most up to date version of the remote repository.
git fetch upstream
You are now ready to create a new branch to start your work and base the
v2.2.x-release release branch
git checkout -b my-changes-branch upstream/v2.2.x-release
“checkout” switches branches
“-b” is an option to create a new branch before switching
“my-changes-branch” will be the name of the new branch
“upstream/v2.2.x-release” is where you want to start your new branch
You should now confirm that you are in the correct branch.
git status # On branch my-changes-branch nothing to commit (working directory clean)
Okay. Let’s pause for a minute.
You have set-up the necessary tools and cloned the source, but if you are going to start making changes to BigBlueButton code you need to understand how the parts interact.
Below is an overview of the different components in a production set-up. When developing you want to change your configuration settings to load new changes instead of the ones deployed for production.
As you can see, nginx is configured to load the client from
/var/www/bigbluebutton/client directory and forward calls to web-api on tomcat7 (note: In BigBlueButton 2.2 the web API now runs as a separate process and no longer uses tomcat7). During development, you need to tell nginx to load from your development directory (
After going through the steps below, you will end up with the following setup.
The components that run in Red5 don’t change when you deploy the development files for bbb-apps, bbb-voice, bbb-video, and bbb-deskshare into
/usr/share/red5. However, notice that the client and web-api are served from different places.
Developing the HTML5 client
$ cd ~/dev/bigbluebutton/bigbluebutton-html5
$ curl https://install.meteor.com/ | sh
The HTML5 client in BigBlueButton 2.2 depends on Meteor version 1.8.x. Navigate to
bigbluebutton-html5/ and set the appropriate version of Meteor
meteor update --allow-superuser --release 1.8
There is one change required to settings.yml to get webcam and screenshare working in the client (assuming you’re using HTTPS already). The first step is to find the value for
kurento.wsUrl packaged settings.yml.
grep "wsUrl" /usr/share/meteor/bundle/programs/server/assets/app/config/settings.yml
Next, edit the development settings.yml and change
wsUrl to match what was retrieved before.
$ vi private/config/settings.yml
You’re now ready to run the HTML5 code. First shut down the packaged version of the HTML5 client so you are not running two copies in parallel.
$ sudo systemctl stop bbb-html5
Install the npm dependencies.
$ meteor npm install
Finally, run the HTML5 code.
$ npm start
By default, the client will run in
development mode. Loading into production environment can be done by passing the value of
$ NODE_ENV=production npm start
Using NODE_ENV=production is not meant to be actually used in production, see here for more information. Instead, you should build the meteor app so that the
bbb-html5 service can work with it.
First, ensure that you’re in the
bigbluebutton-html5 directory. If you follow the instructions above and have
ubuntu as your user, you can run the following:
meteor build --server-only /home/ubuntu/dev/bigbluebutton/bigbluebutton-html5/meteorbundle
Meteor will build your customized version into a
.tar.gz so we need to unpack it and place it in the right directory for
bbb-html5 to use it. Run:
sudo tar -xzvf /home/ubuntu/dev/bigbluebutton/bigbluebutton-html5/meteorbundle/*.tar.gz -C /usr/share/meteor
Finally, start the HTML5 client with
sudo systemctl start bbb-html5.
There we go! Remember that this will be overwritten every time you upgrade, so you may want to have some mechanism put in place to replace it, or if your changes add new functionality/solve a bug, consider upstreaming them. To avoid having to uninstall and reinstall the
bbb-html5 package to restore a working version, you may want to make a copy of the original
HTML5 Coding Practices
For coding conventions related to the HTML5 code refer to this document.
All configurations are located in /private/config/settings.yml. If you make any changes to the YAML configuration you will need to restart the meteor process.
During Meteor.startup() the configuration file is loaded and can be accessed through the Meteor.settings.public object.
The bbb-common-message is required by a few components of BigBlueButton. So it is required to build this first. Otherwise, you will run into compile errors.
cd ~/dev/bigbluebutton/bbb-common-message ./deploy.sh
First, we need to update the latest bigbluebutton.properties file according to your setup. Basically, you will have to change the URL and security salt. If you don’t know your salt, run
sudo bbb-conf --salt
cd ~/dev/bigbluebutton/ # Edit the file and change the values of bigbluebutton.web.serverURL and securitySalt. vi bigbluebutton-web/grails-app/conf/bigbluebutton.properties
Now you need to give your user account access to upload slides to the presentation directory and also access to write log files.
sudo chmod -R ugo+rwx /var/bigbluebutton sudo chmod -R ugo+rwx /var/log/bigbluebutton
Open the file
~/.sbt/1.0/global.sbt using your editor
mkdir -p ~/.sbt/1.0 vi ~/.sbt/1.0/global.sbt
Add the following into it
resolvers += "Artima Maven Repository" at "http://repo.artima.com/releases" updateOptions := updateOptions.value.withCachedResolution(true)
cd ~/dev/bigbluebutton/bbb-common-web ./deploy.sh
Now let’s start building bbb-web
We need to stop the bbb-web service
sudo service bbb-web stop
Download the necessary libraries.
Start grails and tell to listen on port 8090
grails -reloading -Dserver.port=8090 run-app
If you get an error
Could not resolve placeholder 'apiVersion', just run
grails -Dserver.port=8090 run-war again. The error is grails not picking up the “bigbluebutton.properties” the first time.
Now test again if you can join the demo meeting.
The command above will run a development version of bbb-web, but if you want to deploy your custom-built bbb-web you need to package a war file.
Instructions for deploying bbb-web
First we need to compile all the project in a single war file.
war application is generated under
Create a new directory and open it.
mkdir exploded && cd exploded
Extract the war content in the newly create directory
jar -xvf ../build/libs/bigbluebutton-0.10.0.war
Then copy the
run-prod.sh after checking all the jar dependencies are listed in
cp ../run-prod.sh .
In the next step we will make a copy of the current production directory for
sudo cp -R /usr/share/bbb-web /usr/share/bbb-web-old
Then we will delete all the files we need to be copied for production
sudo rm -rf /usr/share/bbb-web/assets/ /usr/share/bbb-web/META-INF/ /usr/share/bbb-web/org/ /usr/share/bbb-web/run-prod.sh /usr/share/bbb-web/WEB-INF/
Next, let’s copy the complied files into the production directory
sudo cp -R . /usr/share/bbb-web/
Make sure the copied files have the right user ownership.
$ sudo chown bigbluebutton:bigbluebutton /usr/share/bbb-web $ sudo chown -R bigbluebutton:bigbluebutton /usr/share/bbb-web/assets/ /usr/share/bbb-web/META-INF/ /usr/share/bbb-web/org/ /usr/share/bbb-web/run-prod.sh /usr/share/bbb-web/WEB-INF/
And finally we run the service.
sudo service bbb-web start
If you need to revert back your original production
bbb-web just run the following command. (Don’t forget to stop bbb-web service before doing it)
sudo mv /usr/share/bbb-web /usr/share/bbb-web-dev && /usr/share/bbb-web-old /usr/share/bbb-web
Your compiled code will be under the
/usr/share/bbb-web-dev directory and you can safely run the original production ``bbb-web`.
You can manually run the application.
cd ~/dev/bigbluebutton/akka-bbb-apps ./run.sh
You need to build the FS ESL library
cd ~/dev/bigbluebutton/bbb-fsesl-client ./deploy.sh
Then you can run the application.
cd ~/dev/bigbluebutton/akka-bbb-fsesl ./run.sh
Legacy Flash applications
For instructions for building the legacy applications related to the Flash client and red5 see this document. Note: The core BigBlueButton development team recommends using the HTML5 client instead of the legacy Flash client.
Localization with Transifex
We use Transifex for crowdsourcing for BigBlueButton Internationalization(i18n). The following steps are not a part of the typical installation and are only required for bringing the language strings in github up to date. There are two ways to pull the translation files; using the transifex.sh script or the transifex client.
The transifex.sh script aims to make retrieving translation files on the Transifex servers as simple as possible. In order to use the script, you must provide your Transifex credentials which have the appropriate authorization. The script can be used in the following ways.
$ ./transifex.sh all
Using the all argument will tell the script to download all available translation files.
$ ./transifex.sh fr de pt-BR
If you only need a specific set of translations, the script can be run with the required locales as argument.
Setup & Configure Transifex Client
This is an alternative method to using the transifex.sh and is essentially the manual process for retrieving translation files from the Transifex servers.
1. Install Transifex Client
To installation the Transifex client we use pip, a package management system designed to manage and install Python packages.
$ sudo apt-get install python-pip
Next we use Pip to install the Transifex client.
$ sudo pip install transifex-client
The following command is used to upgrade the client to the most current version.
$ pip install --upgrade transifex-client
2. Transifex Project Initialization
tx init command is used to initialize a project. Run from the root directory of the application.
$ tx init Creating .tx folder. . . Transifex instance [https://www.transifex.com]:
Press Enter (will be prompted for your Transifex username and password)
Creating skeleton... Creating config file... Done.
This will create a Transifex project file in the current directory containing the project’s configuration file.
3. Transifex Client configuration
The Transifex client uses a per project configuration file. This is located in .tx/config of your project’s root directory and is generated on running the
tx init command. It should be updated with the following configuration:
[main] host = https://www.transifex.com [bigbluebutton-html5.enjson] file_filter = private/locales/<lang>.json source_file = private/locales/en_US.json source_lang = en_US type = KEYVALUEJSON
4. Set a Project Remote
tx set allows you to configure and edit Transifex project files on your local computer.
The following command is used to initialize a local project for the remote project specified by the URL.
$ tx set --auto-remote https://www.transifex.com/projects/p/bigbluebutton-html5/resources/enjson/
Next we can pull language files located on the Transifex server.
5. Pull: Download Transifex Translations
To pull all translation files from the Transifex server, the following command is used.
$ tx pull -a bigbluebutton-html5.enjson
In the event that there are a lot of translations, instead of pulling all, we can specify which translations we want to acquire.
$ tx pull -r bigbluebutton-html5.enjson -l pt_BR
Alternatively, simply download a ZIP archive of all languages in the project from the Transifex project page and unarchive it in the
Welcome to Nginx page
If you get the “Welcome to Nginx” page. Check if bigbluebutton is enabled in nginx. You should see bigbluebutton in
If not, enable it.
sudo ln -s /etc/nginx/sites-available/bigbluebutton /etc/nginx/sites-enabled/bigbluebutton sudo /etc/init.d/nginx restart
Pausing/Restarting VM gives wrong date in commit
If you are developing using a VM and you’ve paused the VM and later restart it, the time on the VM will be incorrect. The incorrect time will affect any commits you do in GitHub.
To ensure your VM has the correct time, you can install ntp with
sudo apt-get install ntp sudo /etc/init.d/ntp restart
and then do the following after starting the VM from a paused state
sudo /etc/init.d/ntp restart
The above will re-sync your clock.
To setup Samba
sudo apt-get install -y --force-yes samba
Then setup your shared directory by editing
; BigBlueButton: Share the development directory [ubuntu] comment = BigBlueButton Development share path = /home/ubuntu browseable = yes read only = no create mask = 0755 directory mask = 0775 guest ok = yes force user = ubuntu
See install-samba-server-ubuntu-16-04 for more info.