bigbluebutton-Github/DEVELOPMENT.md

This document provides instructions for developers to setup their
environment and work on the upcoming BBB 1.1 (tentative release version).

## Install BBB 1.0

Make sure you have a working BBB 1.0 before you proceed with the instructions below.

## Install OpenJDK 8

```
sudo add-apt-repository ppa:openjdk-r/ppa
sudo apt-get update
sudo apt-get install openjdk-8-jdk
```

Change the default jre. Choose Java 8.

```
sudo update-alternatives --config java
```

Change the default jdk. Choose Jdk8

```
sudo update-alternatives --config javac
```

## Environment Variables

Edit `~/.profile` and change `JAVA_HOME`

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

Save the file and refresh environment vars.

```
source ~/.profile
```

## Update Development Tools

### Install The Core Development Tools

```
sudo apt-get install git-core ant
```


### Install Gradle

```
cd ~/dev/tools
wget http://services.gradle.org/distributions/gradle-2.12-bin.zip
unzip gradle-2.12-bin.zip
ln -s gradle-2.12 gradle 
```

### Install Grails

```
cd ~/dev/tools
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
```

### Install Maven

```
cd ~/dev/tools
wget apache.parentingamerica.com//maven/maven-3/3.3.3/binaries/apache-maven-3.3.3-bin.zip
unzip apache-maven-3.3.3-bin.zip
ln -s apache-maven-3.3.3 maven
```

### Install sbt

```
cd ~/dev/tools
wget https://dl.bintray.com/sbt/native-packages/sbt/0.13.9/sbt-0.13.9.tgz
tar zxvf sbt-0.13.9.tgz
```

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 Flex SDK is unpacked, you 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 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.

```
sudo 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/*
sudo 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.

```
cd ~/dev/tools/
mkdir -p apache-flex-sdk-4.13.0-bin/frameworks/libs/player/11.2
cd 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
sudo sed -i "s/11.1/11.2/g" frameworks/flex-config.xml
sudo sed -i "s/<swf-version>14<\/swf-version>/<swf-version>15<\/swf-version>/g" frameworks/flex-config.xml
sudo 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 FLEX_HOME=$HOME/dev/tools/flex
export PATH=$PATH:$FLEX_HOME/bin

export GRADLE_HOME=$HOME/dev/tools/gradle
export PATH=$PATH:$GRADLE_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 


```

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

## Setup Red5

```
cd /usr/share

# Make a backup of the deployed red5

sudo mv red5 red5-orig

# Symlink red5 to old red5

sudo ln -s red5-orig red5
```

## Build Red5

Build red5-parent 

```
cd ~/dev
git clone https://github.com/bigbluebutton/red5-parent.git
cd red5-parent/
git checkout snapshot-mar-30-2016
mvn install
```

Build red5-io

```
cd ~/dev
git clone https://github.com/bigbluebutton/red5-io.git
cd red5-io
git checkout snapshot-mar-30-2016
./bbb-build.sh
```

Build red5-server-common

```
cd ~/dev
git clone https://github.com/bigbluebutton/red5-server-common.git
cd red5-server-common
git checkout snapshot-mar-30-2016
./bbb-build.sh
```

Build red5-server

```
cd ~/dev
git clone https://github.com/bigbluebutton/red5-server.git
cd red5-server
git checkout snapshot-mar-30-2016
./build-red5.sh

# Deploy red5, this will copy the new red5 to /usr/share
# and modify the symlink you created above.

./deploy-red5.sh
```

# Developing the client


# 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 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 service nginx restart
Restarting nginx: the configuration file /etc/nginx/nginx.conf syntax is ok
configuration file /etc/nginx/nginx.conf test is successful nginx.
```

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

Build build a specific locale (en_US default)

```
ant locale -DLOCALE=en_US
```

To build all locales

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


## Setup nginx

Create file `/etc/bigbluebutton/nginx/screenshare.nginx` and add the following:

```
# Handle desktop sharing.  Forwards
# requests to Red5 on port 5080.
location /screenshare {
  proxy_pass         http://127.0.0.1:5080;
  proxy_redirect     default;
  proxy_set_header   X-Forwarded-For   $proxy_add_x_forwarded_for;
  client_max_body_size       10m;
  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;
}
```

Restart nginx

```
sudo service nginx restart
```

## Build BBB Red5 Applications

Turn off red5 service

```
sudo service bbb-red5 stop
```

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

### Build common-message

```
cd ~/dev/bigbluebutton/bbb-common-message/
sbt publish
sbt publishLocal
```

### Build bbb-apps

```
cd ~/dev/bigbluebutton/bigbluebutton-apps/
gradle resolveDeps
gradle clean war deploy
```

### Build bbb-voice

```
cd ~/dev/bigbluebutton/bbb-voice
```

Edit `src/main/webapp/WEB-INF/bigbluebutton-sip.properties`
Make sure the IP addresses point to yout BBB server.

```
bbb.sip.app.ip=192.168.74.128

# The ip and port of the FreeSWITCH server
freeswitch.ip=192.168.74.128
```

```
gradle resolveDeps
gradle clean war deploy
```

### Build bbb-video

```
cd ~/dev/bigbluebutton/bbb-video/
gradle resolveDeps
gradle clean war deploy
```

### Build bbb-screenshare

```
cd ~/dev/bigbluebutton/bbb-screenshare/app
```

Edit `src/main/webapp/WEB-INF/screenshare.properties`
Make sure the following points to your BBB server.

```
streamBaseUrl=rtmp://192.168.74.128/screenshare
jnlpUrl=http://192.168.74.128/screenshare
jnlpFile=http://192.168.74.128/screenshare/screenshare.jnlp
```

Build and deploy

```
./deploy.sh
```

## Stop services


```
sudo /etc/init.d/bbb-red5 stop
sudo service bbb-apps-akka stop
sudo service bbb-fsesl-akka stop
```

Remove old `bbb-web` app from tomcat

```
sudo rm /var/lib/tomcat7/webapps/bigbluebutton.war
```

## Manually start services

### Run Red5

Open up a terminal.

```
cd /usr/share/red5
sudo -u red5 ./red5.sh
```

### Run Akka Apps

Open up another terminal.

```
cd ~/dev/bigbluebutton/akka-bbb-apps
sbt run
```

### Run Akka FSESL App

Open another terminal

```
cd ~/dev/bigbluebutton/akka-bbb-fsesl
sbt run
```

### Run bbb-web

```
cd ~/dev/bigbluebutton/bigbluebutton-web
```

Get the salt and BBB URL from `/var/lib/tomcat7/webapps/demo/bbb_api_conf.jsp`

Edit `grails-app/conf/bigbluebutton.properties` and change the following with
the salt and IP you got from above.

```
bigbluebutton.web.serverURL=http://192.168.74.128
securitySalt=856d5e0197b1aa0cf79897841142a5f6
```

Start bbb-web

```
gradle resolveDeps
grails clean
grails -Dserver.port=8888 run-war
```

If things started without errors, congrats!