Welcome to the BigBlueButton Developer’s Guide for BigBlueButton 1.1-beta.

    You’ll need to have a working BigBlueButton 1.1-beta server before you can setup a development environment (see installation steps).

    Overview

    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
    • bbb-client – Flash based client that loads within the browser
    • bbb-apps – Server side application for sending and receiving messages with the Flash client
    • akka-bbb-apps – Server side application that handles the state of meetings on the server
    • bbb-deskshare – Desktop sharing server

    You don’t need to understand everything about each component, but you do need to understand the overall architecture and how the components work together.

    This document describes how to setup a development environment using an existing BigBlueButton 1.1 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 1.1 (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, use VMWare Player or VirtualBox to create first an Ubuntu 16.04 64-bit virtual machine (VM). The associated documentation for VMWare Player and VirtualBox will guide you on setting up a new 16.04 64-bit VM.

    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.

    Root Privileges

    Important: Make sure you create another user such as “firstuser” 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 “firstuser”, but they will apply to any account that has the permissions to execute commands as root, such as

    sudo ls
    

    wget

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

    vi ~/.profile
    

    Add the following line at the end of the file

    export JAVA_HOME=/usr/lib/jvm/java-8-openjdk-amd64
    

    Reload your profile (this will happen automatically when you next login, but we’ll do it explicitly here to load the new environment variable).

    source ~/.profile
    

    Do a quick test to ensure JAVA_HOME is set.

    $ echo $JAVA_HOME
    /usr/lib/jvm/java-8-openjdk-amd64
    

    Next, you need to make a directory to hold the tools needed for BigBlueButton development.

    mkdir -p ~/dev/tools
    cd ~/dev/tools
    

    You need to download a number of tools with wget and then unpack each of these tools in the above directory.

    wget http://services.gradle.org/distributions/gradle-2.12-bin.zip
    unzip gradle-2.12-bin.zip
    ln -s gradle-2.12 gradle
    
    wget https://github.com/grails/grails-core/releases/download/v2.5.2/grails-2.5.2.zip
    unzip grails-2.5.2.zip
    ln -s grails-2.5.2 grails
    
    wget https://dl.bintray.com/sbt/native-packages/sbt/0.13.9/sbt-0.13.9.tgz
    tar zxvf sbt-0.13.9.tgz
    
    wget https://archive.apache.org/dist/maven/maven-3/3.3.3/binaries/apache-maven-3.3.3-bin.tar.gz
    tar zxvf apache-maven-3.3.3-bin.tar.gz
    ln -s apache-maven-3.3.3 maven
    

    In the next step, you need to get the Apache Flex 4.13.0 SDK package.

    Note: Even though we’re downloading the Apache Flex 4.13.0 SDK, BigBlueButton is developed and built with Flex 3 compatibility mode enabled.

    First, you need to download the SDK tarball from an Apache mirror site and then unpack it.

    wget https://archive.apache.org/dist/flex/4.13.0/binaries/apache-flex-sdk-4.13.0-bin.tar.gz
    tar xvfz apache-flex-sdk-4.13.0-bin.tar.gz
    

    Once the Apache Flex SDK is unpacked, you need to download one of the dependencies manually because the file was moved from its original URL.

    wget --content-disposition https://github.com/swfobject/swfobject/archive/2.2.tar.gz
    tar xvfz swfobject-2.2.tar.gz
    cp -r swfobject-2.2/swfobject apache-flex-sdk-4.13.0-bin/templates/
    

    Now that we’ve finished with the first dependency we need to download the Adobe Flex SDK. We’ll do this step manually in case the download fails (if it does, remove the incomplete file and issue the wget command again).

    cd apache-flex-sdk-4.13.0-bin/
    mkdir -p in/
    wget http://download.macromedia.com/pub/flex/sdk/builds/flex4.6/flex_sdk_4.6.0.23201B.zip -P in/
    

    Once the supplementary SDK has downloaded, we can use its build.xml script to automatically download the remaining third-party tools.

    ant -f frameworks/build.xml thirdparty-downloads
    

    After Flex downloads the remaining third-party tools, you need to modify their permissions.

    find ~/dev/tools/apache-flex-sdk-4.13.0-bin -type d -exec chmod o+rx '{}' \;
    chmod 755 ~/dev/tools/apache-flex-sdk-4.13.0-bin/bin/*
    chmod -R +r ~/dev/tools/apache-flex-sdk-4.13.0-bin
    

    Next, create a linked directory with a shortened name for easier referencing.

    ln -s ~/dev/tools/apache-flex-sdk-4.13.0-bin ~/dev/tools/flex
    

    The next step in setting up the Flex SDK environment is to download a Flex library for video.

    mkdir -p ~/dev/tools/apache-flex-sdk-4.13.0-bin/frameworks/libs/player/11.2
    cd ~/dev/tools/apache-flex-sdk-4.13.0-bin/frameworks/libs/player/11.2
    wget http://fpdownload.macromedia.com/get/flashplayer/installers/archive/playerglobal/playerglobal11_2.swc
    mv -f playerglobal11_2.swc playerglobal.swc
    

    The last step to have a working Flex SDK is to configure it to work with playerglobal 11.2

    cd ~/dev/tools/apache-flex-sdk-4.13.0-bin
    sed -i "s/11.1/11.2/g" frameworks/flex-config.xml
    sed -i "s/<swf-version>14<\/swf-version>/<swf-version>15<\/swf-version>/g" frameworks/flex-config.xml
    sed -i "s/{playerglobalHome}\/{targetPlayerMajorVersion}.{targetPlayerMinorVersion}/libs\/player\/11.2/g" frameworks/flex-config.xml
    

    With the tools installed, you need to add a set of environment variables to your .profile to access these tools.

    vi ~/.profile
    

    Copy-and-paste the following text at bottom of .profile.

    
    export GRAILS_HOME=$HOME/dev/tools/grails
    export PATH=$PATH:$GRAILS_HOME/bin
    
    export GRADLE_HOME=$HOME/dev/tools/gradle
    export PATH=$PATH:$GRADLE_HOME/bin
    
    export FLEX_HOME=$HOME/dev/tools/flex
    export PATH=$PATH:$FLEX_HOME/bin
    
    export SBT_HOME=$HOME/dev/tools/sbt
    export PATH=$PATH:$SBT_HOME/bin
    
    export MAVEN_HOME=:$HOME/dev/tools/maven
    export PATH=$PATH:$MAVEN_HOME/bin
    
    export ANT_OPTS="-Xmx512m -XX:MaxPermSize=512m"
    
    

    Reload your profile to use these tools (this will happen automatically when you next login).

    source ~/.profile
    

    Check that the tools are now in your path by running the following command.

    $ mxmlc -version
    Version 4.13.0 build 20140701
    

    Checking out the Source

    With the development tools installed, we’ll next clone the source in the following directory:

    /home/firstuser/dev
    

    Using your GitHub account, do the following

    1. Fork the BigBlueButton repository into your GitHub account
    2. Clone your repository into your ~/dev folder

    After cloning, you’ll have the following directory (make sure the bigbluebutton directory is within your dev directory).

    /home/firstuser/dev/bigbluebutton
    

    Confirm that you are working on the master branch.

    cd /home/firstuser/dev/bigbluebutton
    git status
    

    You should see

    # On branch master
    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. The development for 1.1 (currently 1.1-beta) is occurring on the master branch.

    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 new branch off master.

    git checkout -b my-1.1-work upstream/master
    

    “checkout” switches branches

    “-b” is an option to create a new branch before switching

    “my-1.1-work” will be the name of the new branch

    “upstream/master” 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-1.1-work
    nothing to commit (working directory clean)
    

    Production Environment

    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.

    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. During development, you need to tell nginx to load from your development directory (/home/firstuser/dev/bigbluebutton)

    After going through the steps below, you will end up with the following setup.

    development

    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.

    Client Development

    With the development environment checked out and the code cloned, we are ready to start developing!

    This section will walk you through making a simple change to the BigBlueButton client.

    Setting up the environment

    The first thing you need to do is to copy the template config.xml file to the build directory for the client.

    cd ~/dev/bigbluebutton/
    cp bigbluebutton-client/resources/config.xml.template bigbluebutton-client/src/conf/config.xml
    

    The config.xml file is one of the first files loaded by the BigBlueButton client when it connects to the server. The config.xml file tells BigBlueButton client how to load the remaining components (such as chat module, deskshare module, video conf module, etc.) and sets a number of configuration parameters for each component. The config.xml specifies the hostname (or IP address) for loading each component.

    Let’s look at the first ten lines of the config.xml file you just copied.

    $ head -n 10 bigbluebutton-client/src/conf/config.xml
    <?xml version="1.0" ?>
    <config>
        <localeversion suppressWarning="false">0.9.0</localeversion>
        <version>VERSION</version>
        <help url="http://HOST/help.html"/>
        <javaTest url="http://HOST/testjava.html"/>
        <porttest host="HOST" application="video/portTest" timeout="10000"/>    
        <bwMon server="HOST" application="video/bwTest"/>
        <application uri="rtmp://HOST/bigbluebutton" host="http://HOST/bigbluebutton/api/enter"/>
        <language userSelectionEnabled="true" />
    

    You will see the word HOST where there would be configured hostname/IP address. You need to change the text HOST to the IP address (or hostname) of your BigBlueButton server. For example, if the IP address of your BigBlueButton server is 192.168.1.145, then using the following command you can easily substitute all occurrences of HOST with 192.168.1.145.

    Note: Don’t copy-and-paste the following command as-is: the address 192.168.1.145 is likely not the correct IP address (or hostname) for your BigBlueButton server. Substitute the IP address (or hostname) for your BigBlueButton server.

    sed -i s/HOST/192.168.1.145/g bigbluebutton-client/src/conf/config.xml
    

    After you’ve done the above command, take a quick look at the file and ensure all instances of HOST are properly replaced with the IP address (or hostname) of your BigBlueButton server.

    The config.xml is ultimately loaded by the BigBlueButton client when a user joins a session on the server.

    Later on, when you deploy your modified client to the BigBlueButton server, there will be two BigBlueButton clients on your server: your modified BigBlueButton client and the default BigBlueButton packaged client (again, this is good as you can switch back and forth). However, the BigBlueButton configuration command sudo bbb-conf only modifies the packaged BigBlueButton client and you will need to mirror any changes to the packaged config.xml to the secondary client’s config.xml.

    Next, you need to setup nginx to redirect calls to the client towards your development version. If you don’t already have an nginx client development file at /etc/bigbluebutton/nginx/client_dev, create one with the following command.

    NOTE: Make sure to replace “firstuser” with your own username if it’s different.

    echo "
    location /client/BigBlueButton.html {
    	root /home/firstuser/dev/bigbluebutton/bigbluebutton-client;
    	index index.html index.htm;
    	expires 1m;
    }
    
    # BigBlueButton Flash client.
    location /client {
    	root /home/firstuser/dev/bigbluebutton/bigbluebutton-client;
    	index index.html index.htm;
    }
    " | sudo tee /etc/bigbluebutton/nginx/client_dev 
    

    Check the contents to ensure it matches below.

    Again, make sure you change /home/firstuser to match your home directory.

    $ cat /etc/bigbluebutton/nginx/client_dev
    
    location /client/BigBlueButton.html {
    	root /home/firstuser/dev/bigbluebutton/bigbluebutton-client;
    	index index.html index.htm;
    	expires 1m;
    }
    
    # BigBlueButton Flash client.
    location /client {
    	root /home/firstuser/dev/bigbluebutton/bigbluebutton-client;
    	index index.html index.htm;
    }
    

    These rules tell nginx where to find the BigBlueButton client. Currently, nginx is using the rules with the default BigBlueButton client through a symbolic link.

    $ ls -al /etc/bigbluebutton/nginx/client.nginx
    lrwxrwxrwx 1 root root 31 2013-05-05 15:44 /etc/bigbluebutton/nginx/client.nginx -> /etc/bigbluebutton/nginx/client
    

    Modify this symbolic link so it points to the development directory for your BigBlueButton client.

    sudo ln -f -s /etc/bigbluebutton/nginx/client_dev /etc/bigbluebutton/nginx/client.nginx
    

    Check that the modifications are in place.

    $ ls -al /etc/bigbluebutton/nginx/client.nginx
    lrwxrwxrwx 1 root root 35 2013-05-05 21:07 /etc/bigbluebutton/nginx/client.nginx -> /etc/bigbluebutton/nginx/client_dev
    

    Now we need to restart nginx so our changes take effect.

    $ sudo systemctl restart nginx
    $ sudo systemctl status nginx
    Unknown operation stataus.
    root@t4:~# systemctl status nginx
    ● nginx.service - A high performance web server and a reverse proxy server
       Loaded: loaded (/lib/systemd/system/nginx.service; enabled; vendor preset: enabled)
       Active: active (running) since Sun 2017-01-15 22:43:31 UTC; 9s ago
      Process: 14264 ExecStop=/sbin/start-stop-daemon --quiet --stop --retry QUIT/5 --pidfile /run/nginx.pid (code=exited, status=0/SUCCESS)
      Process: 14266 ExecStart=/usr/sbin/nginx -g daemon on; master_process on; (code=exited, status=0/SUCCESS)
      Process: 14265 ExecStartPre=/usr/sbin/nginx -t -q -g daemon on; master_process on; (code=exited, status=0/SUCCESS)
     Main PID: 14267 (nginx)
        Tasks: 9
       Memory: 5.6M
          CPU: 37ms
       CGroup: /system.slice/nginx.service
               ├─14267 nginx: master process /usr/sbin/nginx -g daemon on; master_process on
               ├─14268 nginx: worker process
               ├─14269 nginx: worker process
               ├─14270 nginx: worker process
               ├─14271 nginx: worker process
               ├─14272 nginx: worker process
               ├─14273 nginx: worker process
               ├─14274 nginx: worker process
               └─14275 nginx: worker process
    
    Jan 15 22:43:31 t4 systemd[1]: Starting A high performance web server and a reverse proxy server...
    Jan 15 22:43:31 t4 systemd[1]: Started A high performance web server and a reverse proxy server.
    
    

    Now, when you launch the BigBlueButton client, nginx will serve the client from your development directory. Next, we need to rebuild the client.

    Building the client

    Let’s now build the client. Note we’re going to build and run the client to make sure it works before making any changes to the source.

    First, we’ll build the locales (language translation files). If you are not modifying the locales, you only need to do this once.

    cd ~/dev/bigbluebutton/bigbluebutton-client
    ant locales
    

    This will take about 10 minutes (depending on the speed of your computer). Next, let’s build the client

    ant
    

    This will create a build of the BigBlueButton client in the /home/firstuser/dev/bigbluebutton/bigbluebutton-client/client directory.

    Note: The BigBlueButton server will cache the config.xml for a given meetingID. To ensure you load the new config.xml you must restart your BigBlueButton server after making a change to the config.xml.

    The above note is important. It’s easy to make a quick change to your config.xml and wonder why the change is not reflected when you load the client. You need to restart BigBlueButton using

    sudo bbb-conf --clean
    

    After this, point your browser to your BigBlueButton server and login to the demo page. The client should start properly.

    Note: You could have also restart BigBlueButton with sudo bbb-conf --restart, but it’s a good idea to pass --clean instead as it cleans out all the log files between restarts and thereby wipes any previous errors.

    Note: On the bottom of the client you’ll see “VERSION”, but that’s OK. It is usually replaced by the latest build number when packaging is done. If you see “VERSION”, this is good as BigBlueButton is now loading your own copy of the client (and not the packaged version).

    If you execute sudo bbb-conf --check, you’ll notice it gives a warning

    ** Potential problems described below **
    # Warning: nginx is not serving the client from /var/www/bigbluebutton/.
    # Instead, it's being served from
    #
    #    /home/firstuser/dev/bigbluebutton/bigbluebutton-client
    #
    # (This is OK if you have setup a development environment.)
    

    This is good – it’s another confirmation that the BigBlueButton server is serving your development client (not the packaged version).

    Making a change

    Now that we have successfully built and loaded the client from a development environment, let’s make a small visible change to the interface. We’re using vi to edit the client, but you can use any Unix text editor of course.

    Note: If you are on Windows and developing using a VM, you may find it easier to setup Samba so you can access your files through Windows Explorer and use a Windows editor. To setup Samba, type the command bbb-conf --setup-samba. You can then browse the network from your Windows computer and find the shared volume. Once mounted in Windows (usually with a drive letter such as d: or e:), you can access the files directly with your editor on Windows.

    cd ~/dev/bigbluebutton/bigbluebutton-client
    vi src/org/bigbluebutton/main/views/MainApplicationShell.mxml
    

    Once you have MainApplicationShell.mxml open, go to line 680 and you’ll see the following text

    <mx:Text htmlText="{ResourceUtil.getInstance().getString('bbb.mainshell.copyrightLabel2',[appVersion])}" id="copyrightLabel2"/>
    

    Insert the text ‘ – BigBlueButton Rocks!!’ as shown below.

    <mx:Text htmlText="{ResourceUtil.getInstance().getString('bbb.mainshell.copyrightLabel2',[appVersion])} -- BigBlueButton Rocks!!!" id="copyrightLabel2"/>
    

    Now, rebuild the BigBlueButton client again.

    ant
    

    When done, join the demo meeting using the client. You’ll see the message -- BigBlueButton Rocks! added to the copyright line.

    rocks

    If you don’t see your changes, try clearing your browser’s cache and then load the client again. It also might be easier to just try this using Firefox since it most likely will not cache this.

    Switching back to the packaged client

    To switch back to using the packaged BigBlueButton client anytime, you only need to change the symbolic link for nginx and then restart BigBlueButton (again, this reloads the config.xml file for the client).

    sudo ln -s -f /etc/bigbluebutton/nginx/client /etc/bigbluebutton/nginx/client.nginx
    sudo bbb-conf --clean
    

    To switch back to your development setup, simply recreate the symbolic link and restart nginx.

    sudo ln -s -f /etc/bigbluebutton/nginx/client_dev /etc/bigbluebutton/nginx/client.nginx
    sudo bbb-conf --clean
    

    Using Flex/Flash Builder

    These steps assume that you have a local BigBlueButton development server on your network (or in a virtual machine). The steps will have you install Samba on the server to give your Windows/Mac access to the file system to make code edits directly.

    Do not install samba on a BigBlueButton server on the internet. Instead, if you want to use Flex/Flash Builder, first setup a local BigBlueButton server on your network (or in a virtual machine) and make the changes locally. After you’ve updated the local BigBlueButton server, copy to modified files (and update any necessary configuration changes) to the remote BigBlueButton server.

    To develop the client using Flash Builder on a local BigBlueButton server (we’ll refer to the local server as the BigBlueButton VM, but it need not be a virtual machine you have for development), follow these steps:

    1. Install Flash Builder on your Windows/Mac machine.

    2. Setup samba on the BigBlueButton VM (use the command sudo bbb-conf --setup-samba) and mount the VM drive as described earlier in this document.

    3. In Flash Builder, import the project by going to File -> Import -> Flash Builder Project.

      1. Select the Project Folder radio

      2. Click Browse and choose the bigbluebutton-client directory in your BigBlueButton VM. For example W:\dev\source\bigbluebutton\bigbluebutton-client

      3. Click Finish.

    4. From the BigBlueButton VM, copy the Flex SDK from ~/dev/tools into the Flash Builder SDK directory. You can see the location on the image below. Then, in Flash Builder, click Window -> Preferences -> Installed Flex SDKs and Add the SDK you have just copied.

    flex-sdk

    1. Right-click on the project, go to Properties -> Flex Compiler, and change the Flex version to 4.13. Make sure the Flash Player specific version is set to at least 11.2.0. Also, check the Flex 3 compatibility mode option (The BigBlueButton client uses Flex 3 components). Click Apply.

    flex-compiler

    1. Right-click on the project, click Properties -> Flex Build Path. Click on MX only component set. Make sure the libs directory is present in the Library path.

    flex-build-path

    Debugging with Flash Builder

    First we will set up our Flash Builder project for debugging.

    1. Right-click on the project, go to Debug As -> Debug Configurations….

    2. Right-click on Web Application -> New

    3. Make sure the BigBlueButton client is in the Project section and src/BigBlueButton.mxml is in the Application file.

    4. Deselect Use default and change the path to about:blank

    5. Select Apply and Close

    Flash Builder is now set up to debug with a client running remotely (ie. on your VM). It is important to note that you must still build the client using ant in your VM because Flash Builder won’t build the full client.

    Before you are able to debug you must have Firefox installed and the debug version of Flash Player for Firefox.

    To start debugging:

    1. Start a BigBlueButton session.

    2. In Flash Builder, open the Debug Configurations…, select your previously created configuration, select Debug

    3. Go back to Firefox and right-click the Flash content, select Debugger, select Localhost

    4. In Flash Builder, wait for the launch progress to get above 50%

    5. Go back to Firefox and select Connect

    The debugger should now be connected and you should see output in the Flash Builder Console and breakpoints will activate. An alternative to steps 3-5 is to wait for the progress to get above 50% and then reload the BigBlueButton.html page in Firefox. The debugger should automatically connect when the Flash content has loaded.

    If you can see messages in the Flash Builder Console, but breakpoints aren’t working you need to make sure that the version of the client in Flash Builder is the same as the version on your server. To do this do a full build of the client with ant on your server and refresh the project in Flash Builder (right-click the project -> Refesh) before running the debugger again. Sometimes the debugger still won’t work after a refresh and you have to restart Flash Builder to get it running again.

    Pulling localization from Transifex

    To pull the localization from Transifex, do the following steps

    1. Install the Transifex client for Ubuntu
    sudo apt-get install python-pip -y
    sudo pip install transifex-client
    
    1. Go to the locale folder
    cd /home/firstuser/dev/bigbluebutton/bigbluebutton-client/locale 
    
    1. Initialize the Transifex project
    tx init
    
    # Insert your transifex user and password
    
    1. Set the BigBlueButton transifex resource
    tx set --auto-remote https://www.transifex.com/projects/p/bigbluebutton/resource/bbbresourcesproperties/
    
    1. Edit the Transifex configuration file to filter the languages to match the BBB repository
    vi .tx/config
    
    file_filter = <lang>/bbbResources.properties 
    
    1. Update all the languages from Transifex (updates only the languages existing in the current directory where the command is executed)
    tx pull -f
    
    Pull all the languages from Transifex (download also languages which don't exist in the local directory where the command is executed, may download undesired language directories [lt, es_429])
    
    tx pull -a
    
    1. Sometimes Transifex downloads es_419 instead of es_LA (Latin American Spanish), in that case we need to manually update es_LA with what is in es_419
    rm -r es_LA
    cp es_419 es_LA
    
    1. Add a gitignore to ignore the .tx folder or remove the .tx folder that is hidden
    nano .gitignore
    .tx
    

    or

    rm -r .tx
    
    1. Compile to check you didn’t break anything
    cd /home/firstuser/dev/bigbluebutton/bigbluebutton-client
    ant locales
    

    Developing BBB-Client-Check

    First, let’s navigate to the source code for the component

    cd ~/dev/bigbluebutton/bbb-client-check
    

    Then modify the configurations fileto substitute your IP or domain name for the word HOST.

    sed -i s/HOST/<IP or domain name>/g resources/config.xml.template
    

    Next, let’s build the component

    ant
    

    This will create a build of the bbb-client-check component in the /home/firstuser/dev/bigbluebutton/bbb-client-check/check directory.

    Next we need to create an nginx file to redirect calls to your development bbb-client-check.

    echo "
    location /check {
    	root /home/firstuser/dev/bigbluebutton/bbb-client-check;
    	index index.html index.htm;
    }
    " | sudo tee /etc/bigbluebutton/nginx/check.nginx > /dev/null 2>&1
    

    Now restart nginx and test the configuration:

    sudo /etc/init.d/nginx restart
    sudo nginx -t
    

    At this point you should be able to navigate to the check client page in your browser and use it. (e.x. http://demo.bigbluebutton.org/check)

    When you make a change you will need to run ant again to rebuild the module.

    Developing BBB-Web

    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 /home/firstuser/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
    

    Now you need to create the nginx file that will redirect calls to your development bbb-web.

    echo "
    # Handle request to bbb-web running within Tomcat. This is for
    # the BBB-API and Presentation.
    location /bigbluebutton {
    	proxy_pass http://127.0.0.1:8888;
    	proxy_redirect default;
    	proxy_set_header X-Forwarded-For \$proxy_add_x_forwarded_for;
    
    	# Allow 30M uploaded presentation document.
    	client_max_body_size 30m;
    	client_body_buffer_size 128k;
    
    	proxy_connect_timeout 90;
    	proxy_send_timeout 90;
    	proxy_read_timeout 90;
    
    	proxy_buffer_size 4k;
    	proxy_buffers 4 32k;
    	proxy_busy_buffers_size 64k;
    	proxy_temp_file_write_size 64k;
    
    	include fastcgi_params;
    }
    " | sudo tee /etc/bigbluebutton/nginx/web_dev > /dev/null 2>&1
    

    Now we just need to create a link to make sure that the requests are redirected properly then restart nginx.

    sudo ln -s -f /etc/bigbluebutton/nginx/web_dev /etc/bigbluebutton/nginx/web.nginx
    sudo /etc/init.d/nginx restart
    

    Now let’s start grails webapp.

    cd /home/firstuser/dev/bigbluebutton/bigbluebutton-web/
    

    Download the necessary libraries.

    gradle resolveDeps
    

    Tell grails to listen on port 8888

    grails -Dserver.port=8888 run-war
    

    or

    grails -reloading -Dserver.port=8888 run-app
    

    If you get an error Could not resolve placeholder 'apiVersion', just run grails -Dserver.port=8888 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.

    grails war
    

    This will create a file with the name bigbluebuttonv0.7dev.war. The version number for the file doesn’t matter, but you should rename the war file to bigbluebutton.war. You then need to deploy the archive to tomcat. You can do this by simply copying it into the tomcat7 webapps directory.

    sudo cp target/bigbluebutton-0.9.0.war /var/lib/tomcat7/webapps/bigbluebutton.war
    

    And now just restart tomcat.

    systemctl restart tomcat7 
    

    If you changed the linking of web.nginx as instructed above you will need to also revert that back to the packaged location for bbb-web.

    sudo ln -s -f /etc/bigbluebutton/nginx/web /etc/bigbluebutton/nginx/web.nginx
    systemctl restart nginx
    

    Developing the Red5 Applications

    You need to make red5/webapps writeable. Otherwise, you will get a permission error when you try to deploy into Red5.

    sudo chmod -R 777 /usr/share/red5/webapps
    

    Developing BBB-Apps

    Before you build and deploy bbb-apps you need to make sure that red5 service is stopped.

    sudo systemctl stop red5
    

    Now you can compile and deploy bigbluebutton-apps.

    cd /home/firstuser/dev/bigbluebutton/bigbluebutton-apps
    gradle resolveDeps
    gradle clean war deploy
    

    And finally, you can start the red5 service up again.

    sudo systemctl start red5
    

    Developing BBB-Video

    First, you need to stop red5.

    sudo systemctl stop red5
    

    Then you can compile and deploy the application.

    cd /home/firstuser/dev/bigbluebutton/bbb-video
    gradle resolveDeps
    gradle war deploy
    

    And finally, start red5 up again.

    sudo systemctl start red5 
    

    Developing Akka-Apps

    First you need to stop bbb-apps-akka service.

    sudo systemctl stop bbb-apps-akka 
    

    Then you can manually run the application.

    cd /home/firstuser/dev/bigbluebutton/akka-bbb-apps
    sbt clean
    sbt run
    

    Developing Akka-FSESL

    First, you need to stop bbb-fsesl-akka service.

    sudo systemctl stop bbb-fsesl-akka
    

    Then you can run the application.

    cd /home/firstuser/dev/bigbluebutton/akka-bbb-fsesl
    sbt clean
    sbt run
    

    Developing BBB-Common-Messages

    If you are modifying an existing message or adding a new one you will need to rebuild bbb-common-messages.

    BBB-common-messages is used as dependency of several BigBlueButton core components. When you update it, you will need to increase the version number and re-publish it so that the other core components pick up the new version of bbb-common-messages and start using them instead.

    For example: In the file /home/firstuser/dev/bigbluebutton/bbb-common-message/build.sbt Change version := "0.0.18" to version := "0.0.19-SNAPSHOT". We recommend you keep the name as “…-SNAPSHOT” until you are happy with your changes and you are ready to publish bbb-common-messages to sonatype. Also temporarily comment out the code for pushing to sonatype:

    // publishTo := {
    //   val nexus = "https://oss.sonatype.org/"
    //   if (isSnapshot.value)
    //     Some("snapshots" at nexus + "content/repositories/snapshots")
    //   else
    //     Some("releases"  at nexus + "service/local/staging/deploy/maven2")
    // }
    
    

    Then uncomment the code for publishing to the local maven repo:

    publishTo := Some(Resolver.file("file",  new File(Path.userHome.absolutePath+"/.m2/repository")))
    
    

    Save the file. You can now compile bbb-common-messages:

    cd /home/firstuser/dev/bigbluebutton/bbb-common-message
    sbt clean
    sbt compile
    

    Once the compile finishes successfully, you can publish bbb-common-messages locally:

    sbt publish
    sbt publishLocal
    

    Change the bbb-common-messages version required in the components akka-bbb-apps and akka-bbb-fsesl. In the files /home/firstuser/dev/bigbluebutton/akka-bbb-apps/build.sbt and /home/firstuser/dev/bigbluebutton/akka-bbb-fsesl/build.sbt substitute the line "org.bigbluebutton" % "bbb-common-message" % "0.0.18" with "org.bigbluebutton" % "bbb-common-message" % "0.0.19-SNAPSHOT". Now restart the two processes:

    cd /home/firstuser/dev/bigbluebutton/akka-bbb-apps
    sbt clean
    sbt run
    

    and

    cd /home/firstuser/dev/bigbluebutton/akka-bbb-fsesl
    sbt clean
    sbt run
    

    You are now using the updated bbb-common-messages. Whenever you are happy with the result you can remove the “-SNAPSHOT” from the version.

    Developing BBB-Voice

    First, you need to stop red5.

    sudo systemctl stop bbb-red5 
    

    Then you can compile and deploy the application.

    cd /home/firstuser/dev/bigbluebutton/bbb-voice
    gradle resolveDeps
    gradle war deploy
    

    And finally, start red5 up again.

    sudo systemctl start bbb-red5 
    

    Developing Deskshare

    Needs to be updated to work with new screenshare JNLP.

    Troubleshooting

    Connecting to the server

    When the BigBlueButton client loads, it runs a number of modules: chat, voice, desktop sharing, and presentation. Each of these modules makes a connection back to their corresponding BigBlueButton server components.

    The URL for each connection is specified in config.xml.

    When setting up a development environment for the client, the config.xml file for the BigBlueButton client is now loaded from ~/dev/bigbluebutton/bigbluebutton-client/client/conf/config.xml. This means that any changes made to the default config.xml by sudo bbb-conf --setip <hostname> will not affect the config.xml in your development environment. Thus, if you change your hostname or IP address for the BigBlueButton server, you’ll need to manually change the config.xml for your development environment.

    Welcome to Nginx page

    If you get the “Welcome to Nginx” page. Check if bigbluebutton is enabled in nginx. You should see bigbluebutton in /etc/nginx/sites-enabled.

    If not, enable it.

    sudo ln -s /etc/nginx/sites-available/bigbluebutton /etc/nginx/sites-enabled/bigbluebutton
    
    sudo /etc/init.d/nginx restart
    

    Old Translation

    If you get a “Old Translation” warning when starting the client, in /var/www/bigbluebutton/client/conf/config.xml change

    <localeversion suppressWarning="false">0.71</localeversion>
    

    to

    <localeversion suppressWarning="false">0.9.0</localeversion>
    

    Warning: Try increasing the code cache size

    If you get a compiler warning during the building of bbb-client, such as

    build-polling:
        [mxmlc] Loading configuration file /home/dwelch/dev/tools/flex-4.5.0.20967/frameworks/flex-config.xml
    OpenJDK 64-Bit Server VM warning: CodeCache is full. Compiler has been disabled.
    OpenJDK 64-Bit Server VM warning: Try increasing the code cache size using -XX:ReservedCodeCacheSize=
        [mxmlc] /home/dwelch/dev/bigbluebutton/bigbluebutton-client/client/PollingModule.swf (232039 bytes)
    

    Add the following to ~/.profile

    export ANT_OPTS="-Xmx512m -XX:MaxPermSize=512m -XX:ReservedCodeCacheSize=1024m"
    

    and then reload the .profile with the command source ~/.profile.

    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.

    Developing Using Eclipse

    These instructions assume that you are developing with a VM running on a Windows machine.

    Set-up Samba

    bbb-conf --setup-samba 
    

    Now map the VM as a network drive.

    For each project, you need to generate Eclipse project files. Therefore, in bbb-app, you run the following to generate the project file.

    gradle eclipse
    

    Then you can import the project into Eclipse by clicking on File->New-> Java Project. Uncheck “Use default location” and browse to the project you want to import.