Alpha release

    IMPORTANT NOTE

    Greenlight v3 is still in the Alpha version. Therefore, it is NOT a production ready application. It contains some missing/incomplete features and should only be used for testing and exploration.

    For any suggestions, notes, encountered issues or questions kindly refer to the Greenlight official repository: http://github.com/bigbluebutton/greenlight/ And the Google community group: https://groups.google.com/g/bigbluebutton-greenlight


    Greenlight is an open source LGPL-3.0 licensed web application that enables organizations having a BigBlueButton server with a complete web conferencing platform in a matter of minutes while being simple to set and to use for both regular and power users.

    Greenlight v3 is a full stack web application built with the latest versions of Ruby on Rails and React. This stack empowers millions of projects and is trusted by big corporations, all while conforming with Greenlight’s licensing subject and the expectations of our community.

    Installation steps

    Keycloak & Authentication

    In v3, Greenlight offers 3 ways of handling authentication:

    1. Local Accounts
    2. External Authentication through Keycloak
    3. External Authentication through OpenId

    By default, Greenlight ships with Keycloak to provide system administrators an easy way to configure authentication.

    If you don’t plan on using Keycloak, you can skip any of the installation steps that mention Keycloak.

    Once you’ve completed the install steps, you can follow the instructions below to correctly configure authentication to match your needs.

    To correctly configure Keycloak with your chosen Identity Provider, see Configuring Keycloak.

    To connect to another authentication broker through OpenID, see Connecting to Another OpenID Provider.

    If don’t plan on using Keycloak, and you would like to completely remove it from your system, see Removing Keycloak.


    Prerequisites

    The following guides requires that your system has two valid FQDNs (Fully Qualified Domain Names) one for Greenlight and another Keycloak that we will configure the nginx proxy to expect.

    So for example, an organization having a public valid domain name of xlab.bigbluebutton.org, it may create two DNS records one with a hostname of “gl” and another of “kc” forming two valid public FQDNs that points to their system public IP address.

    We will configure the scripts and services afterwards to use those public valid FQDNs gl.xlab.bigbluebutton.org and kc.xlab.bigbluebutton.org for Greenlight and Keycloak.

    To create these new FQDNs please refer to your DNS registrar and follow their guides on how to add new records.

    Once done, it may take some time for the DNS updates to propagate through the network so please make sure that the records became available. You can refer to these platforms for verification https://www.whatsmydns.net/.

    We also expect that both of the FQDNs points to your local system public IP address and that you have web ports (both HTTP(TCP 80) and HTTPS(TCP 443) ) opened for inbound traffic.


    Installing Docker

    To run Greenlight, you must install Docker Engine alongside a Docker Client. You have 2 options:

    Note: Some systems may be using the docker-compose utility. In these guides we will be using docker compose in the commands, but you can still use docker-compose utility in place without any issues.

    If docker dependencies are installed correctly running the following commands should have a similar output:

    sudo docker version
    sudo docker compose version # sudo docker-compose version
    

    Docker Version

    NOTE: You do not have to install both of docker compose and docker-compose. You may use either to follow the guides.


    Cloning the repository

    We have included a few deployment scripts to facilitate the setup of Greenlight in this dedicated GitHub public repository.

    The scripts are written in Bash. If your system does not have Bash installed and you run into issues please refer to your distribution documentation on how to install Bash. The scripts will be expecting the Bash binaries to be under “/bin/bash”.

    We will start by cloning the repository in our local system for that we will need to have git CLI installed. To verify that git is installed you can run:

    git version
    

    You should have a message indicating the installed version in your system.

    Git Version

    If not installed please refer to the official documentations on how to install git.

    Go to the home directory:

    cd ~
    

    To clone the repository we will run:

    git clone https://github.com/bigbluebutton/greenlight-run.git
    cd greenlight-run
    git checkout alpha
    

    Setting environmental variables

    To setup the .env files, run the following commands:

    cp data/greenlight/dotenv data/greenlight/.env
    cp dotenv .env
    

    In v3, there are 2 main .env files:

    • ~/greenlight-run/.env (for the entire deployment)
    • ~/greenlight-run/data/greenlight/.env (for Greenlight ONLY)

    Most Greenlight required variables are pre-set by default - there are few variables to set yourself.

    For documentation purposes, the tables below are included to further describe the required environmental variables that we need to set, their purpose and our recommendations.

    To check the full list of all Greenlight environmental variables, please refer to Greenlight environmental variables.

    ./.env:

    Variable Name Description Default Value Required
    LETSENCRYPT_EMAIL The email address to use when generating Let’s encrypt SSL (x509) certificates withinit-letsencrypt.sh script. - YES (when using the init-letsencrypt.sh script)
    DOMAIN_NAME The domain name that greenlight and keycloak will be accessible through. The domain name should be a valid DNS name that has active records registered in the DNS network. This is required for generating SSL certificates. - YES
    GL_HOSTNAME The Greenlight hostname. Along with the DOMAIN_NAME variable this will form the FQDN for Greenlight. gl YES
    KC_HOSTNAME The Keycloak hostname. Along with the DOMAIN_NAME variable this will form the FQDN for Keycloak. kc YES (when deploying Keycloak)
    POSTGRES_PASSWORD The password for the Postgres super user. It’s required to set this to a secure random complex value. - YES
    KEYCLOAK_PASSWORD The Keycloak admin account password. It’s required to set this to a secure inaccessible random complex value. - YES (when deploying Keycloak)

    ./data/greenlight/.env:

    Variable Name Description Default Value Required
    DATABASE_URL The URI of the Postgres instance. This should match the following format: postgres://postgres:$POSTGRES_PASSWORD@postgres:5432 - YES
    SECRET_KEY_BASE A secret key that Greenlight will use for cryptographic purposes. It’s required to set this to a secure inaccessible random complex value. - YES

    All non-required variables should be already preset.

    The variables in the .env files can be edited by uncommenting (removing any # at the start of) the line that defines the variable and change their values with the following syntax VARIABLE_NAME=**<Your_Value>**.

    The required variables (those not commented but empty) can be edited directly or run these commands for your convenience.

    Please note that it’s highly recommended to generate secure complex random secrets and passwords so it is suggested not to set those variables manually.

    For your convenience, you can run these commands to auto generate secure random complex secrets:

    sed -i "s/SECRET_KEY_BASE=.*/SECRET_KEY_BASE=$(openssl rand -hex 64)/" data/greenlight/.env
    psql_pwd="$(openssl rand -hex 40)";kc_pwd="$(openssl rand -hex 40)"
    sed -i "s/POSTGRES_PASSWORD=.*/POSTGRES_PASSWORD=$psql_pwd/" .env
    sed -i "s/KEYCLOAK_PASSWORD=.*/KEYCLOAK_PASSWORD=$kc_pwd/" .env
    sed -i "s/DATABASE_URL=.*/DATABASE_URL=postgres:\/\/postgres:$psql_pwd@postgres:5432/" data/greenlight/.env
    unset psql_pwd kc_pwd;
    

    Creating Keycloak database

    If you don’t plan on using Keycloak, you can skip this section.

    To create your Keycloak database, run the following command:

    sudo docker compose up postgres -d
    

    Wait a few seconds and create the keycloak database needed by Keycloak application, by runnning:

    sudo docker exec -it postgres psql -U postgres -c 'CREATE DATABASE keycloakdb;'
    

    It should output something similar to this:

    Keycloak DB


    Starting Greenlight

    Now that everything is set, start the Greenlight services through docker compose:

     sudo docker compose up -d
    

    You can verify the containers status by running:

    sudo docker container ls
    

    It should output something similar to this:

    Docker Containers

    Note: If you have followed the steps on how to disable Keycloak, it is normal to have a slightly different output that looks similar but does not contain the keycloak container.

    Notice how all Greenlight services are having an Up status which indicates that they are up and running without any issues.

    Now, you should be able to access your Greenlight and and Keycloak instances through their URLs

    So for DOMAIN_NAME=xlab.bigbluebutton.org, GL_HOSTNAME=gl and KC_HOSTNAME=kc. You can access Greenlight through: http://gl.xlab.bigbluebutton.org/ and Keycloak through http://kc.xlab.bigbluebutton.org.

    If you receive a 502 Bad Gateway error, please wait a few seconds and refresh the page. If you receive an nginx welcome page, restart the nginx service sudo docker compose restart nginx


    Certificates & HTTPS

    Both Greenlight and Keycloak should now be accessible through HTTP only.

    However, we do not recommend the use of the HTTP plain protocol unless for testing purposes. Besides, Keycloak and some browser features on Greenlight will only be available through HTTPS so for your security and the convenience of your users we highly encourage you to follow the next steps to enable secure HTTPS access to Greenlight.

    To setup your certificates to work with Greenlight, see Certificates