Customizing the Landing Page

Before you begin

IMPORTANT
If you installed using the bbb-install.sh script, then you must switch to
the Customize version of Greenlight first, before you proceed.

Switching
from Install to Customize
In the case that you would like to make changes to your code without losing
your current data, there are steps you can take to switch from
the Install version to the Customize version without losing any data.
In the Greenlight directory, take down Greenlight and rename the Greenlight
directory to avoid conflicts using these commands:
docker-compose down
cd ..
mv greenlight/ greenlight-old/
Then, install Greenlight by following the Customize instructions

Customizing Greenlight
Greenlight is written in Ruby on Rails. If you know how Ruby on Rails works,
you can easily customize Greenlight to your own needs.
The default install instructions will run Greenlight within docker. To customize
Greenlight, you’ll want to checkout the source code and build your own
docker image.

1. Install Docker
The official Docker documentation is the best resource for Docker install
steps. To install Docker (we recommend installing Docker CE unless you
have a subscription to Docker EE),
Install Docker Engine on Ubuntu
Estimated reading time: 11 minutes

To get started with Docker Engine on Ubuntu, make sure you meet the prerequisites, then install
Docker.

Prerequisites
OS requirements
To install Docker Engine, you need the 64-bit version of one of these Ubuntu versions:

 Ubuntu Eoan 19.10

 Ubuntu Bionic 18.04 (LTS)
 Ubuntu Xenial 16.04 (LTS)

Docker Engine is supported on x86_64 (or amd64), armhf, arm64, s390x (IBM Z), and ppc64le (IBM
Power) architectures.

Uninstall old versions

Older versions of Docker were called docker, docker.io, or docker-engine. If these are installed,
uninstall them:
$ sudo apt-get remove docker docker-engine docker.io containerd runc

It’s OK if apt-get reports that none of these packages are installed.

The contents of /var/lib/docker/, including images, containers, volumes, and networks, are
preserved. The Docker Engine package is now called docker-ce.

Supported storage drivers

Docker Engine on Ubuntu supports overlay2, aufs and btrfs storage drivers.
Docker Engine uses the overlay2 storage driver by default. If you need to use aufs instead, you
need to configure it manually. See use the AUFS storage driver

Installation methods
You can install Docker Engine in different ways, depending on your needs:
  Most users set up Docker’s repositories and install from them, for ease of installation and
upgrade tasks. This is the recommended approach.
 Some users download the DEB package and install it manually and manage upgrades
completely manually. This is useful in situations such as installing Docker on air-gapped
systems with no access to the internet.
 In testing and development environments, some users choose to use
automated convenience scripts to install Docker.

Install using the repository

Before you install Docker Engine for the first time on a new host machine, you need to set up the
Docker repository. Afterward, you can install and update Docker from the repository.

SET UP THE REPOSITORY

1. Update the apt package index and install packages to allow apt to use a repository over
HTTPS:
2. $ sudo apt-get update
3.
4. $ sudo apt-get install \
5. apt-transport-https \
6. ca-certificates \
7. curl \
8. gnupg-agent \
9. software-properties-common

10. Add Docker’s official GPG key:

11. $ curl -fsSL https://download.docker.com/linux/ubuntu/gpg | sudo apt-
key add -

Verify that you now have the key with the fingerprint 9DC8 5822 9FC7 DD38 854A E2D8
8D81 803C 0EBF CD88, by searching for the last 8 characters of the fingerprint.

$ sudo apt-key fingerprint 0EBFCD88

pub rsa4096 2017-02-22 [SCEA]

9DC8 5822 9FC7 DD38 854A E2D8 8D81 803C 0EBF CD88
uid [ unknown] Docker Release (CE deb) <[email protected]>
 sub rsa4096 2017-02-22 [S]

12. Use the following command to set up the stable repository. To add
the nightly or test repository, add the word nightly or test (or both) after the
word stable in the commands below. Learn about nightly and test channels.
Note: The lsb_release -cs sub-command below returns the name of your Ubuntu
distribution, such as xenial. Sometimes, in a distribution like Linux Mint, you might need to
change $(lsb_release -cs) to your parent Ubuntu distribution. For example, if you are
using Linux Mint Tessa, you could use bionic. Docker does not offer any guarantees on
untested and unsupported Ubuntu distributions.

o x86_64 / amd64
$ sudo add-apt-repository \
"deb [arch=amd64] https://download.docker.com/linux/ubuntu \
$(lsb_release -cs) \
stable"

INSTALL DOCKER ENGINE

1. Update the apt package index, and install the latest version of Docker Engine and
containerd, or go to the next step to install a specific version:
2. $ sudo apt-get update
3. $ sudo apt-get install docker-ce docker-ce-cli containerd.io

Got multiple Docker repositories?

If you have multiple Docker repositories enabled, installing or updating without specifying a
version in the apt-get install or apt-get update command always installs the highest
possible version, which may not be appropriate for your stability needs.

4. To install a specific version of Docker Engine, list the available versions in the repo, then
select and install:

a. List the versions available in your repo:

$ apt-cache madison docker-ce

 docker-ce | 5:18.09.1~3-0~ubuntu-xenial |
https://download.docker.com/linux/ubuntu xenial/stable amd64 Packages
docker-ce | 5:18.09.0~3-0~ubuntu-xenial |
https://download.docker.com/linux/ubuntu xenial/stable amd64 Packages
docker-ce | 18.06.1~ce~3-0~ubuntu |
https://download.docker.com/linux/ubuntu xenial/stable amd64 Packages
docker-ce | 18.06.0~ce~3-0~ubuntu |
https://download.docker.com/linux/ubuntu xenial/stable amd64 Packages
...

b. Install a specific version using the version string from the second column, for
example, 5:18.09.1~3-0~ubuntu-xenial.
$ sudo apt-get install docker-ce=<VERSION_STRING> docker-ce-
cli=<VERSION_STRING> containerd.io

5. Verify that Docker Engine is installed correctly by running the hello-world image.
6. $ sudo docker run hello-world

This command downloads a test image and runs it in a container. When the container runs, it
prints an informational message and exits.

Docker Engine is installed and running. The docker group is created but no users are added to it.
You need to use sudo to run Docker commands. Continue to Linux postinstall to allow non-privileged
users to run Docker commands and for other optional configuration steps.
.
Before moving onto the next step, verify that Docker is installed by running:
docker -v

2. Install Greenlight
Using your GitHub account, do the following

1. Fork the Greenlight repository into your GitHub account

2. Clone your repository onto your local machine

git clone https://github.com/bigbluebutton/greenlight.git

After cloning, you’ll have the following directory:

~/greenlight
Confirm that you are working on the master branch.
cd greenlight
git status
You should see
On branch master
Your branch is up to date with 'origin/master'.

nothing to commit, working tree clean

When you first clone the Greenlight git repository, git will place you, by
default, on the master branch, which is the latest code for Greenlight. The
release branch for v2 is on the v2 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/greenlight.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
Greenlight 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 v2
git checkout -b custom-changes upstream/v2
You should now confirm that you are in the correct branch.
git status

On branch custom-changes
Your branch is up to date with 'upstream/v2'.
nothing to commit, working tree clean

3. Configure Greenlight
Greenlight will read its environment configuration from the .env file. To
generate this file, enter ~/greenlight directory and run:
cp sample.env .env
If you open the .env file you’ll see that it contains information for all of the
Greenlight configuration options. Some of these are mandatory.

Generating a Secret Key

Greenlight needs a secret key in order to run in production. To generate this,
run:
docker run --rm bigbluebutton/greenlight:v2 bundle exec rake secret
Inside your .env file, set the SECRET_KEY_BASE option to the last line in this
command. You don’t need to surround it in quotations.

Setting BigBlueButton Credentials

By default, your Greenlight instance will automatically connect to test-
install.blindsidenetworks.com if no BigBlueButton credentials are
specified. To set Greenlight to connect to your BigBlueButton server (the one
it’s installed on), you need to give Greenlight the endpoint and the secret. To
get the credentials, run:
bbb-conf --secret
In your .env file, set the BIGBLUEBUTTON_ENDPOINT to the URL, and
set BIGBLUEBUTTON_SECRET to the secret.

Setting Allowed Hosts

For reasons related to security, you’ll also need to specify the domain from
which the application will be accessible from.
In your .env file, set the SAFE_HOSTS to your domain. If Greenlight is
accessible
at https://bbb.example.com/b then SAFE_HOSTS=bbb.example.com
Configure Specific Settings
Other than the 3 configurations listed above, there are many different options
for configuring Greenlight. All possible configurations are listed in
the .env file.
You can find more info on specific settings that can be configured here.

Verifying Configuration
Once you have finished setting the environment variables above in
your .env file, to verify that you configuration is valid, run:
docker run --rm --env-file .env bigbluebutton/greenlight:v2 bundle
exec rake conf:check
If you have configured an SMTP server in your .env file, then all four tests
must pass before you proceed. If you have not configured an SMTP server,
then only the first three tests must pass before you proceed.

4. Configure Nginx to Route To

Greenlight
Greenlight will be configured to deploy at the /b subdirectory. This is
necessary so it doesn’t conflict with the other BigBlueButton components.
The Nginx configuration for this subdirectory is stored in the Greenlight
image. To add this configuration file to your BigBlueButton server, run:
cat ./greenlight.nginx | sudo tee
/etc/bigbluebutton/nginx/greenlight.nginx
Verify that the Nginx configuration file
(/etc/bigbluebutton/nginx/greenlight.nginx) is in place. If it is, restart
Nginx so it picks up the new configuration.
systemctl restart nginx
This will routes all requests to https://<hostname>/b to the Greenlight
application. If you wish to use a different relative root, you can follow the
steps outlined here.
Optionally, if you wish to have the default landing page at the root of your
BigBlueButton server redirect to Greenlight, add the following entry to the
bottom of /etc/nginx/sites-available/bigbluebutton just before the
last } character.
location = / {
return 307 /b;
}
To have this change take effect, you must once again restart Nginx.

5. Start Greenlight 2.0

To start the Greenlight Docker container, you must install docker-compose,
which simplifies the start and stop process for Docker containers.
Install docker-compose by following the steps for installing on Linux in
the Docker documentation. You may be required to run all docker-
compose commands using sudo. If you wish to change this, check
out managing docker as a non-root user .

Using docker-compose
Before you continue, verify that you have docker-compose installed by
running:
docker-compose -v
Once you have verified that it is installed correctly, create your Docker image
by running (image name can be any name of your choosing):
./scripts/image_build.sh <image name> release-v2
Example
./scripts/image_build.sh bigbluebutton/greenlight release-v2
Next, in the docker-compose.yml file, replace:
services:
app:
entrypoint: [bin/start]
image: bigbluebutton/greenlight:v2
With
services:
app:
entrypoint: [bin/start]
image: <image name>:release-v2
Finally, from the ~/greenlight directory, start the application using:
docker-compose up -d
This will start Greenlight, and you should be able to access it
at https://<hostname>/b.
The database is saved to the BigBlueButton server so data persists when you
restart. This can be found at ~/greenlight/db.
All of the logs from the application are also saved to the BigBlueButton
server, which can be found at ~/greenlight/log.
If you don’t wish for either of these to persist, simply remove the volumes
from the docker-compose.yml file.
To stop the application, run:
docker-compose down

Using docker run

docker run is no longer the recommended way to start Greenlight. Please
use docker-compose.
If you are currently using docker run and want to switch to docker-compose,
follow these instructions.

Making Code Changes

Using the text editor/IDE of choice, you can edit any of the files in the
directory. The majority of Greenlight’s code lives in ~/greenlight/app.
You can see an example of how to customize the Landing Page here.
To see your changes reflected in Greenlight, you will need to restart
Greenlight.

Restart Greenlight
After you edit the .env file or make any change to the code, you are required
to rebuild the Greenlight image in order for it to pick up the changes. Ensure
you are in the Greenlight directory when restarting Greenlight. To do this,
enter the following commands:
docker-compose down
./scripts/image_build.sh <image name> release-v2
docker-compose up -d
Updating to the Latest Version of
Greenlight
If a new version of Greenlight has been released, you’ll need to fetch the
most up to date version of the remote repository.
git fetch upstream
To merge the code:
git merge upstream/v2
Once you’ve merged your code, you should look through the latest version of
the sample.env file here, and see if there are any new settings you would like
to change or add to Greenlight. If you come across something you want to
add, simply copy paste it to the bottom of your .env, then restart Greenlight.

here. Don’t worry about any of the .env configuration, as it will be overwritten
by the version you are currently using.
Copy over your database file and .env file using these commands:
cp ~/greenlight-old/.env ~/greenlight/.env
sudo cp -r ~/greenlight-old/db ~/greenlight/
Finally, restart Greenlight with:
cd ~/greenlight
docker-compose down
docker-compose up -d
Updating the code
A common customization is to modify the default landing page. For a simple
change, let’s rename the welcome banner to say “Welcome to MyServer”.
The welcome banner is generated by index.html.erb. To customize this
message, open app/views/main/index.html.erb in an editor.
<%
# BigBlueButton open source conferencing system -
http://www.bigbluebutton.org/.
# Copyright (c) 2018 BigBlueButton Inc. and by respective authors
(see below).
# This program is free software; you can redistribute it and/or
modify it under the
# terms of the GNU Lesser General Public License as published by
the Free Software
# Foundation; either version 3.0 of the License, or (at your
option) any later
# version.
#
# BigBlueButton is distributed in the hope that it will be useful,
but WITHOUT ANY
# WARRANTY; without even the implied warranty of MERCHANTABILITY or
FITNESS FOR A
# PARTICULAR PURPOSE. See the GNU Lesser General Public License for
more details.
# You should have received a copy of the GNU Lesser General Public
License along
# with BigBlueButton; if not, see <http://www.gnu.org/licenses/>.
%>

<div class="background">
<div class="container pt-9 pb-8">
 <div class="row">
<div class="col-md-12 col-sm-12 text-center">
<h1 id="main-text" class="display-4 mb-4"> <%=
t("landing.welcome").html_safe %></h1>
<p class="lead offset-lg-2 col-lg-8 col-sm-12 "><%=
t("landing.about", href: link_to(t("greenlight"),
"https://bigbluebutton.org/2018/07/09/greenlight-2-0/", target:
"_blank")).html_safe %></p>
<%= link_to "https://youtu.be/Hso8yLzkqj8", target:
"_blank" do %>
<h4><%= t("landing.video") %> <i class="far fa-play-
circle ml-1"></i></h4>
<% end %>
</div>

</div>
</div>
</div>

<%= render "shared/features" %>

This is an Embedded RuBy (ERB) file. Look for the following line:
<h1 id="main-text" class="display-4 mb-4"> <%=
t("landing.welcome").html_safe %></h1>
The function t("landing.welcome") retrieves the localized version of the
label landing.welcome. For English, this retrieves the string from en.yml.
Edit config/locales/en.yml and look for the following section:
landing:
about: "%{href} is a simple front-end for your BigBlueButton
open-source web conferencing server. You can create your own rooms
to host sessions, or join others using a short and convenient
link."
welcome: Welcome to BigBlueButton.
video: Watch our tutorial on using Greenlight
 upgrade: Show me how to upgrade to 2.0!
version: We've released a new version of Greenlight, but your
database isn't compatible.
To change the welcome message, modify the text associated
with landing.welcome to say “Welcome to MyServer”.
welcome: Welcome to MyServer
Save the change to en.yml, and restart Greenlight. The welcome message
should have the new text.