BigBlueButton is an open source web conferencing system for online learning. The project’s goal is to enable teachers to provide remote students anywhere in the world a high-quality online learning experience.


    GreenLight is a super simple front-end for your BigBlueButton server. At its core, Green Light provides a minimalistic web-based interface that lets users

    • Create a meeting
    • Invite others to the meeting
    • Join a meeting

    Furthermore, if you configure GreenLight to use either Gmail or Twitter for authentication, users can login and record meetings and manage the recordings.

    The steps below cover how to use and install GreenLight on your BigBlueButton server.

    The quickest way to create a meeting

    From the user’s perspective, to start a new meeting, simply enter a meeting name - such as “New Meeting” - and GreenLight shows you two options: Invite and Start.


    To Invite other users, GreenLight gives you a uniform resource locater (URL) that you can share with others. Clicking the copy button below the URL copies it to the clipboard; clicking the mail button opens your default email client with the URL in the body.

    To Start the meeting, click the Start button (blue of course). GreenLight will then prompt for your name and, after entering your name, click Join. You will then join the meeting along with anyone else who received the invite URL.


    That’s it – you can create as many meetings you want, as often as you want. In the meeting everyone is a moderator, which means anyone can make themselves the current presenter, upload a presentation, use the white board controls, and share his or her desktop.

    After your leave the meeting, GreenLight remembers the previous names so you can click the name instead of typing it again (GreenLight tries hard to reduce your typing).


    GreenLight offers more capabilities if you login (see next section).

    Create and manage recordings

    When you login using either your Google or Twitter account, GreenLight lets you create recorded meetings and manage the recordings.

    How does GreenLight’s authentication work? It uses a technology called OAuth that first has users authenticate with either their Google or Twitter account and, if successful, GreenLight will receive an authentication token with very limited information. In the case of Twitter, this is only the users name. In the case of Google, it’s the users name and Gmail address. GreenLight can then use the Gmail address to send out e-mail notifications of when a recording is ready.

    When you login to GreenLight, your personal meetings operate differently than a general meeting:

    • users with the invite URL can’t join until you start the meeting, and
    • only you are the moderator (everyone else is a viewer).

    In other words, with your personal meetings, no one can join your meetings until you do.

    You can record meetings

    As moderator, you can record any segment of the meeting by pressing the Start/Stop Record button. You can press the Start/Stop Record button multiple times during the meeting to mark multiple segments for recording. After the meeting finishes, BigBlueButton will create a single playback file of all segments.

    Desktop notifications of users waiting to join

    If you are using FireFox or Chrome, GreenLight will notify you on the desktop (outside the browser) when someone is waiting to join your personal meeting.

    Realtime updates on active meetings

    Not only does GreenLight keep track of your previous meetings, it also lets you know when they are active, along with how many users and moderators are currently in them.


    Email notifications of finished recordings

    After a meeting finishes, you will receive an e-mail notification when the recordings is ready.


    Manage visibility of recordings: Public, Unlisted, and Not Published

    By default, all your recordings are “Unlisted”, which means that GreenLight will not show other users the recording URL. Only you, or anyone else you share this URL with, will be able to view the recording.

    You can change the visibility of recordings anytime within GreenLight (you need to be logged in to do this). A recording can be one of three states: Public, Unlisted, and Not Published.

    Public Unlisted Not Published
    Everyone can view the recording URL at the meeting page. Only users who have the recording URL can view it. No one can view the recording.

    Share recordings

    You can use the share button to share your recordings via email or upload to Youtube (provided they have a video component).


    Delete recordings

    You can delete a recording at anytime.

    Overview Video

    We created the following video to give you an overview of how GreenLight works.

    Installation Video Walkthrough

    Installing GreenLight

    To make it easy to install GreenLight on your BigBlueButton 1,1 (or later) server, we’ve created a Docker image that encapsulates everything into a single container.

    GreenLight is built as Ruby on Rails application. If you don’t want to use the Docker image and, instead, run it from source, see the steps at

    These instructions show how to install GreenLight on your BigBlueButton 1.1 (or later) server using Docker.

    We highly suggest using Docker to install and deploy GreenLight, but if you must, there are instructions for installing from source.


    Before you install, you need the following

    • BigBlueButton 1.1 (or later) server
    • The BigBlueButton server has been configure with a fully qualified hostname with valid SSL certificate

    While you don’t need to configure GreenLight for authentication, if you do it will enable users to have recorded meetings and manage the meetings. To setup GreenLight for authentication, you need

    • A Google Account
    • A Twitter Account
    • A BigBlueButton 1.1 (or later) server configured with SSL

    Having a Google account will enable you to request a client ID and client secret from Google’s API console to allow GreenLight to enable users to login with their (not yours) Google account. It’s a similar configuration for a Twitter account.

    Also, configuring authentication with a Google account will enable GreenLight to send out e-mails when recordings are ready.

    1. Install Docker

    Run all the commands in section as root on your BigBlueButton 1.1 (or later) server.

    First, you need to install Docker. The Docker documentation is the best resource and for the latest steps. To install Docker (recommend installing Docker CE unless you have a subscription to Docker EE), see Instal Docker on Ubuntu.

    Once you have followed the installation steps for Docker, check you have the latest version using the following command (it you should see version 17 or later).

    # docker version
     Version:      17.06.0-ce
     API version:  1.30
     Go version:   go1.8.3
     Git commit:   02c1d87
     Built:        Fri Jun 23 21:23:31 2017
     OS/Arch:      linux/amd64
     Version:      17.06.0-ce
     API version:  1.30 (minimum version 1.12)
     Go version:   go1.8.3
     Git commit:   02c1d87
     Built:        Fri Jun 23 21:19:04 2017
     OS/Arch:      linux/amd64
     Experimental: false

    2. Install GreenLight

    Next, setup directory for running GreenLight.

    # mkdir ~/greenlight
    # cd ~/greenlight

    We need to create a template environment file for GreenLight that we can put in all the settings. To both install GreenLight and create a template environment file (called env), run the following command:

    # docker run --rm bigbluebutton/greenlight cat ./sample.env > env

    Generate Secret Key

    We’re now going to configure GreenLight with the minimal settings to run. First, run the following command to generate a secret key.

    # docker run --rm bigbluebutton/greenlight rake secret

    Next, edit the env file and add assign the output for the above command to SECRET_KEY_BASE. After you edit, it should look like the following (replace <secret> with the output from the above command).

    # Step 1 - Create a secret key for rails
    # You can generate a secure one through the Greenlight docker image
    # with with the command
    #   docker run --rm bigbluebutton/greenlight rake secret

    3. Enter BigBlueButton Credentials

    Next, we need to tell GreenLight how to connect to your BigBlueButton server and issue API commands. Enter the command bbb-conf --secret. For example, here’s what the command looks like when running on (we’ve masked the shared secret).

    # bbb-conf --secret
        Secret: <secret>

    Of course, the URL for your BigBlueButton server will be different than and your secret will be a long string of characters.

    Assign the values for URL and Secret to BIGBLUEBUTTON_ENDPOINT and BIGBLUEBUTTON_SECRET in the env file. It should look something like below

    # Step 2 - Enter credentials for your BigBlueButton Server
    # The endpoint and secret from your bigbluebutton server.  To get these values, run
    # the following command on your BigBlueButton server
    #    bbb-conf --secret
    # and uncomment the following two variables

    Save the changes to env file.

    4. Install Webhooks on your BigBlueButton Server

    Some of the features in GreenLight require webhooks to be installed on your BigBlueButton server.

    To install webhooks, run the following command on your BigBlueButton server:

    # apt-get install bbb-webhooks

    You will also need to tell GreenLight that you have enabled webhooks on your BigBlueButton server. To do this, change the GREENLIGHT_USE_WEBHOOKS environment variable in your env file from false to true.


    5. Run GreenLight Server

    Using Docker you can start your server with the following command

    # cd ~/greenlight
    # docker run -d -p 5000:80 -v $(pwd)/db/production:/usr/src/app/db/production --env-file env --name greenlight bigbluebutton/greenlight

    For more information on docker commands take a look at

    Before trying to access GreenLight, we’ll setup nginx to forward request on <hostname>:5000/b to port 5000 locally. To configure nginx, enter the following command

    # docker run --rm bigbluebutton/greenlight cat ./scripts/greenlight.nginx | sudo tee  /etc/bigbluebutton/nginx/greenlight.nginx

    And restart nginx to have it read the new configuration file.

    # systemctl restart nginx

    After restart, you can access GreenLight with https://<hostname>/b, where <hostname> is the hostname for your BigBlueButton server.

    If you want to replace the default page on your BigBlueButton server with GreenLight, add the following entry to the bottom /etc/nginx/sites-available/bigbluebutton just before the last ‘}’.

         location = / {
           return 301 /b;

    And restart nginx once more

    # systemctl restart nginx

    GreenLight is now the default landing page of your server.

    6. Configure OAuth2 (optional)

    You only need to configure (at least) one OAuth provider to use authenticated meetings. GreenLight supports Google and Twitter.

    Google OAuth

    You can use your own Google account, but since GreenLight will use this account for sending out emails, you may want to create a Google account related to the hostname of your BigBlueButton server. For example, if your BigBlueButton server is called, you may want to create a Google account called greenlight_notifications_myserver.

    You need a Google account to create an OAuth 2 CLIENT_ID and SECRET. The will enable users of GreenLight to authenticate with their own Google account (not yours).

    Login to your Google account, and click the following link

    If you want to see the documentation behind OAuth2 at Google, click the link


    First, enable the “Google+ API”.

    1. Click Dashboard
    2. Click “+Enable APIs”
    3. Click “Google+ API”
    4. Click “Enable”
    5. Click “Credentials”


    1. Click “Create credentials
    2. Select “OAuth client ID
    3. Select “Web application”
    4. Under “Authorized redirect URIs” enter “http://hostname/b/auth/google/callback” where hostname is your hostname
    5. Click “Create”

    A window should open with your OAuth credentials. In this window, copy client ID and client secret to the env file so it resembles the following (your credentials will be different).

    The GOOGLE_OAUTH2_HD environment varaible is optional and can be used to restrict Google authentication to a specific Google Apps hosted domain.

    Twitter OAuth

    You need a Twitter account to create an OAuth 2 client ID and client secret. The will enable users of GreenLight to authenticate with their own Twitter account (not yours).

    Login to your Twitter account, and click the following link:


    1. Click “Create New App”
    2. Under “Callback URL” enter “http://hostname/b/auth/twitter/callback” where hostname is your hostname
    3. Click “Create your Twitter application”
    4. Click “Keys and Access Tokens” tab

    You should see a key and secret. Add the Consumer Key (API Key) (not the OwnerID) and Consumer Secret (API Secret) to the env file (your values will be different)


    LDAP OAuth

    GreenLight is able to authenticate users using an external LDAP server. To connect GreenLight to an LDAP server, you will have to provide values for the environment variables under the ‘LDAP Login Provider’ section in the env file. You need to provide all of the values for LDAP authentication to work correctly.

    LDAP_SERVER is the server host.

    LDAP_PORT is the server port (commonly 389).

    LDAP_METHOD is the authentication method, either ‘plain’ (default), ‘ssl’ or ‘tls’.

    LDAP_UID is the name of the attribute that contains the user id. For example, OpenLDAP uses ‘uid’.

    LDAP_BASE is the location to look up users.

    LDAP_BIND_DN is the default account to use for user lookup.

    LDAP_PASSWORD is the password for the account to perform user lookup.

    Here are some example settings using an OpenLDAP server.


    If your server is still running you will need to recreate the container for changes to take effect.

    See Applying env File Changes section to enable your new configuration.

    Once an OAuth provider is configured GreenLight will allow users to login and use authenticated meetings.

    If you are using an ActiveDirectory LDAP server, you should determine the name of your user id parameter to set LDAP_UID. It is commonly ‘sAMAccountName’ or ‘UserPrincipalName’.

    7. Configuring email notifications (optional)

    There are three steps to configuring email notifications:

    1. Add notify script to BigBlueButton
    2. Configure the Greenlight mailer
    3. Enable the publish callback script

    Add notify script to BigBlueButton

    First, the script requires two gem dependencies jwt and java_properties. To install these gems, run

    # gem install jwt java_properties

    Next, run the following command to install the callback script into BigBlueButton.

    # docker run --rm bigbluebutton/greenlight cat ./scripts/greenlight_recording_notify.rb | sudo tee -a /usr/local/bigbluebutton/core/scripts/post_publish/greenlight_recording_notify.rb
    # chmod +x /usr/local/bigbluebutton/core/scripts/post_publish/greenlight_recording_notify.rb

    BigBlueButton will now execute this script at the end of processing each recording.

    Configure the GreenLight to send emails

    Using the Google account that you configured for OAuth 2 in section Google OAuth, edit env and apply the following settings.


    Do the steps in Applying env file changes to apply the new changes.

    Enable callback for email notifications

    In the env file set


    Do the steps in Applying env file changes to apply the new changes.

    8. Enabling uploading to Youtube (optional)

    In order to allow users to upload their recordings to Youtube, you will need to configure GreenLight to work with Google OAuth2. To do this, see the section on Google OAuth.

    Once you have GreenLight successfully authenticating users with OAuth2, you will need to enable the Youtube Data API within the Google Developer Console. This will allow GreenLight to ask users for permission to access their Youtube account (and upload recordings).


    In order to enable the Youtube Data API, you should follow these steps:

    1. Click Dashboard
    2. Click “+Enable APIs”
    3. Click “Youtube Data API”
    4. Click “Enable”
    5. Click “Credentials”

    Users will be required to authenticate again in order to allow Youtube access. If a user attempts to upload a recording without access, GreenLight will prompt them to reauthenticate.

    Lastly, you will also need to change the ENABLE_YOUTUBE_UPLOADING variable in the env file from false to true. This will make sure GreenLight asks users for permission to access their Youtube accounts when authenticating.

    9. Configuring Slack notifications (optional)

    Enabling Slack notifications will allow GreenLight to send notifications to a Slack channel (or user) when:

    1. A recording is published/unpublished.
    2. A user joins a meeting.
    3. A meeting ends.

    Registering your Slack Webhook

    Follow the steps below to register your Slack Webhook:

    1. Go to
    2. Select your team and click ‘Configure’.
    3. Choose a channel, and select ‘Add Incoming Webhooks Integration’.

    Enabling Slack notifications

    To enable Slack notifications you will need to open your env file and insert values for the SLACK_WEBHOOK and SLACK_CHANNEL environment variables.

    SLACK_WEBHOOK is the webhook you generated for your team on the Slack website (see above).

    SLACK_CHANNEL is the channel you want the notifications to display to. Keep in mind, channels start with a # symbol (#channel_name). You can also send messages directly to a user with the @ symbol (@username). If you don’t specify a channel, the messages will be sent to the channel you selected when registering your webhook.

    Do the steps in Applying env file changes to apply the new changes.

    10. Configuring a custom background (optional)

    By default, GreenLight will use a standard background for its landing image. If you would like to change this background, you can go into the env file and set the LANDING_BACKGROUND variable to a URL that points to an image. For best results, use a large image that takes up most of the screen (such as 1280 x 1024).


    It is important to note that users who have configured custom landing backgrounds on their account will not see the LANDING_BACKGROUND, but rather their own.

    Do the steps in Applying env file changes to apply the new changes.


    Automatically start GreenLight on boot

    To have GreenLight automatically restart when you star the host server, first stop and remove the existing container named ‘greenlight’:

    # docker stop greenlight
    # docker rm greenlight

    and then run Greenlight with the following docker command

    # docker run -d -p 5000:80 --restart=unless-stopped -v $(pwd)/db/production:/usr/src/app/db/production -v $(pwd)/assets:/usr/src/app/public/system --env-file env --name greenlight bigbluebutton/greenlight

    The parameter --restart=unless-stopped will automatically restart the docker image when you restart the computer.

    If you don’t wish to save user content (such as custom landing images) locally on your sever, you can remove -v $(pwd)/assets:/usr/src/app/public/system from the command. They will then be saved in Greenlight’s public directory within the docker container.

    Applying env File Changes

    Whenever you update the env file and want to apply the changes to GreenLight, you must stop GreenLight, delete the container, and run it again.

    To stop GreenLight and remove the existing container named ‘greenlight’, do the following:

    # docker stop greenlight
    # docker rm greenlight

    Then use the same command to start the server

    # docker run -d -p 5000:80 -v $(pwd)/db/production:/usr/src/app/db/production -v $(pwd)/assets:/usr/src/app/public/system --env-file env --name greenlight bigbluebutton/greenlight

    Updating Greenlight to a new version

    To update GreenLight to the latest docker image, do the following command:

    # docker pull bigbluebutton/greenlight

    To stop currently running Greenlight instance:

    # docker stop greenlight
    # docker rm greenlight

    Then use the command to start the BigBlueButton server:

    # docker run -d -p 5000:80 --restart=unless-stopped -v $(pwd)/db/production:/usr/src/app/db/production -v $(pwd)/assets:/usr/src/app/public/system --env-file env --name greenlight bigbluebutton/greenlight

    Setting a prefered client

    A BigBlueButton server has two seperate clients that a user can use, these are the Flash and HTML5 clients. If your server isn’t running the HTML5 client, GreenLight will automatically join all users using the Flash client.

    If you’ve setup the HTML5 client on your server, you can control which client GreenLight will default to. If you set USE_HTML5_BY_DEFAULT to true in the .env file, all non-authenticated users will join using the HTML5 client by default (instead of the Flash client).

    The way GreenLight selects a client for authenticated users is different. If a user is authenticated, they will have the ability to switch their prefered client in their preferences (provided HTML5 is configured on the server). This means that users who have logged in have full control over which client they use and can switch between them.

    It is also worth noting that if the user is on a mobile device, GreenLight will automatically use the HTML5 client, since the Flash client does not work on mobile devices. If a user attempts to join a server that isn’t running the HTML5 client using a mobile device, GreenLight will display a message letting them know they are unable to join because the BigBlueButton server doesn’t support the HTML5 client.

    Disabling guest access

    A user must login to GreenLight to access features such as meeting updates, preferences, recording management, and more. However, GreenLight will allow unauthenticated users to create meetings.

    If you wish to disable guest access and only allow authenticated users to create meetings, you should uncomment and set the DISABLE_GUEST_ACCESS environment variable in the env file to true.


    This will not prevent unauthenticated users from joining meetings created by authenticated users if they have been given the invite URL.

    Disabling guest access will also set a new landing page that welcomes the user to GreenLight, and prompts them to login.

    Do the steps in Applying env file changes to apply the new changes.



    GreenLight logs to log/production.log within the docker container by default. This means that if you recreate your docker container, you will lose all of the logs. To prevent this, you can mount the log directory in the containter to a directory on your host machine. This will mirror the production.log file from within the container and save to the host machine instead.

    To save logs to the host machine, you should include the following option when running GreenLight.

    # -v $(pwd)/log:/usr/src/app/log

    This makes the full run command:

    # docker run -d -p 5000:80 --restart=unless-stopped -v $(pwd)/db/production:/usr/src/app/db/production -v $(pwd)/assets:/usr/src/app/public/system -v $(pwd)/log:/usr/src/app/log --env-file env --name greenlight bigbluebutton/greenlight

    You can then find production.log at ~/greenlight/log.

    If you want to access logs within the docker container without mounting the log directory, you can enter to docker container to retrieve the logs using:

    # docker exec -i -t greenlight /bin/bash

    If you don’t want GreenLight send logs to log/production.log, you can configure it to log to the console instead. To do this, you should comment out the DISABLE_RAILS_LOG_TO_STDOUT environment variable in the env file.

    Installing GreenLight without Docker

    Although GreenLight was designed to be used with Docker, it is possible to install it from source onto a BigBlueButton server. This should only be done if Docker is not an option, and we highly recommend using Docker to deploy GreenLight.

    1. Log into your BigBlueButton server as root.
    2. Ensure you have both Ruby and Ruby on Rails installed on your BigBlueButton server. GreenLight requires a minimum of Ruby 2.4.0 and Rails 5.
    3. Clone the GreenLight repo and switch into the /greenlight directory.
    4. Open up the Gemfile and move the dotenv-rails gem outside of the test/development block.
    5. Install bundler if you need to (gem install bundler), then run bundle. If it fails to bundle the pg gem, run sudo apt-get install libpq-dev then try again.
    6. Copy the file at /scripts/greenlight.nginx to /etc/bigbluebutton/nginx on your BigBlueButton server. To apply the change, restart nginx using systemctl restart nginx.
    7. Return to the /greenlight directory and copy the sample.env file to .env using cp sample.env .env.
    8. Fill out the .env file. For information on how to do this, see the Enter BigBlueButton Credentials section. Make sure to uncomment the BigBlueButton server credentials. To generate the SECRET_KEY_BASE, run rake secret from within the /greenlight directory.
    9. Uncomment the RELATIVE_URL_ROOT=/b line within the .env file.
    10. Migrate the database using RAILS_ENV=production rake db:migrate.
    11. Precompile the assets by running rails assets:precompile.
    12. Start the Greenlight server using rails s -p 5000 -e production.
    13. Navigate to your host at /b to use GreenLight.

    Launching Greenlight in the Host Network

    If you want to run GreenLight on the host network, you can edit the env file and add this line:


    Run this command:

    # docker run -d -p 5000:5000 --restart=unless-stopped -v $(pwd)/db/production:/usr/src/app/db/production -v $(pwd)/assets:/usr/src/app/public/system --env-file env --name greenlight --network=host bigbluebutton/greenlight

    Check Greenlight configuration

    To check Greenlight’s configuration for connecting to a BigBlueButton server use the following command:

    # docker run --rm --env-file env bigbluebutton/greenlight rake conf:check

    To check Greenlight’s mailer configuration use the following command and replace with an email address to receive the test email.

    # docker run --rm --env-file env bigbluebutton/greenlight rake conf:check_email['<your_email>']