Beta release

    IMPORTANT NOTE

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

    For any suggestions, notes, encountered issues or questions, please refer to the Greenlight official repository: http://github.com/bigbluebutton/greenlight/ or 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, and is 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 guide 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 with a valid public domain name of xlab.bigbluebutton.org may create two DNS records: one with the hostname “gl”, and another one “kc”, forming two valid public FQDNs that points to their system public IP address.

    We will configure the scripts and services afterwards to use the valid public 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 the new records have been added, it may take some time for the DNS updates to propagate through the network. Please make sure that the records are available before continuing. You can refer to these platforms for verification https://www.whatsmydns.net/.

    We also expect that both of the FQDNs point to your local system public IP address and that the web ports HTTP(TCP 80) and HTTPS(TCP 443) are open 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 docker compose and docker-compose. You may use either to follow the guides.


    Cloning the repository

    A few deployment scripts to facilitate the setup of Greenlight are included in the 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 are expecting the Bash binaries to be under “/bin/bash”.

    Start by cloning the repository in the local system. For that, the git CLI needs to be installed. To verify that git is installed, you can run:

    git version
    

    There should be a message indicating the installed version in your system.

    Git Version

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

    Go to the home directory:

    cd ~
    

    To clone the repository, run the following:

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

    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 of Greenlight required variables are preset by default, but there are a few variables that have to be set manually.

    For documentation purposes, the tables below are included to further describe the required environmental variables that need to be set, their purpose and the 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 is required to set this to a secure random complex value. - YES
    KEYCLOAK_PASSWORD The Keycloak admin account password. It is 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 used by Greenlight for cryptographic purposes. It is required to set this to a secure inaccessible random complex value. - YES
    SMTP_SERVER The address (e.g. an FQDN) of the remote mailing server having an open SMTP service. In example, to use Google’s mailing server we’d type smtp.google.com in place. - YES (When enabling Mailing).
    SMTP_PORT The port on which the SMTP service is accessible through on the remote SMTP_SERVER. Usually, it’s 25 TCP for SMTP and 465 TCP for SMTPS (SMTP over TLS). - YES (If SMTP_SERVER is set)
    SMTP_USERNAME The username of the account to use when authenticating to the SMTP_SERVER. - YES (If SMTP_SERVER is set)
    SMTP_PASSWORD The password of the account to use when authenticating to the SMTP_SERVER. - YES (If SMTP_SERVER is set)
    SMTP_AUTH The authentication type to use to authenticate to the SMTP_SERVER: plain: sends the credentials in plaintext (DISCAURGAGED unless for testing and while using SMTPS), login: sends the Base64 encoding of the credentials (DISCAURGAGED unless more secure AUTHN methods aren’t supported by the server and while using SMTPS), cram_md5: uses a challenging protocol exchanging cryptographically signed messages via MD5 (ENCAURAGED while also using SMTPS). - YES (If SMTP_SERVER is set)
    SMTP_DOMAIN The domain_name of the SMTP client to provide to the SMTP_SERVER when making an SMTP protocol HELO/EHLO command on the client greeting. Usually, it’s the domain name portion of the SMTP_SENDER_EMAIL FQDN. In example, for google this is required and for an SMTP_SENDER_EMAIL of greenlight@gmail.com this will be gmail.com. - YES (If SMTP_SERVER is set and required by your SMTP server)
    SMTP_SENDER_EMAIL The email sender address to use when making the SMTP protocol MAIL FROM command. This address will be used by Greenlight 3 when sending all emails and is expected to be authorized by the account defined by SMTP_USERNAME and SMTP_PASSWORD. - YES (If SMTP_SERVER is set)
    SMTP_SENDER_NAME The email sender name to use when making the SMTP protocol MAIL FROM command. This name will be used by Greenlight 3 when sending all emails. - YES (If SMTP_SERVER is set)
    SMTP_STARTTLS_AUTO Checks if the SMTP_SERVER supports STARTTLS protocol command and use it to negotiate an upgrade to SMTPS over the initiated unencrypted connection. In case the SMTP_SERVER does not support STARTTLS Greenlight 3 will connect through the plain SMTP protocol when this option is enabled and when both of SMTP_STARTTLS and SMTP_TLS are disabled. Unless it’s necessary and for testing purposes please leave this as recommended. This will not guarantee the security of your emails, for a secure configuration kindly consider using SMTPS on your SMTP_SERVER and enable SMTP_TLS by default or at least ensure the avoidance of insecure connections by enabling SMTP_STARTTLS. true NO
    SMTP_STARTTLS Checks if the SMTP_SERVER supports STARTTLS protocol command and use it to negotiate an upgrade to SMTPS over the initiated unencrypted connection. In case the SMTP_SERVER does not support STARTTLS this option will guarantee that Greenlight 3 will not send emails over insecure connections. It’s recommended in production environments to ensure that START_TLS is enabled on the SMTP_SERVER. false NO
    SMTP_TLS Use SMTPS when connecting to the SMTP_SERVER. Unlike START_TLS command Greenlight 3 will assume that SMTPS is used by default and initiate a secure connection initially. We’re disabling this option by default for a simpler setup and more compatibility with third party mailing services. However, if your provider supports SMTPS by default, kindly enable this option for a maximum security. If your provider does not offer a direct SMTPS connection but rather supports STARTTLS, kindly consider enabling SMTP_STARTTLS instead. false NO
    SMTP_SSL_VERIFY Defines wither or not to enable SSL verification on the certificate of the SMTP_SERVER when connecting through SMTPS. Unless for testing purposes, please leave this enabled. true NO

    All non-required variables should be already preset.

    The variables in the .env files can be edited by uncommenting the line that defines the variable and change the values with the following syntax VARIABLE_NAME=<VALUE>.

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

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

    For convenience, these commands can be run 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 the Keycloak database, run the following command:

    sudo docker compose up postgres -d
    

    Wait a few seconds, then create the keycloak database needed by Keycloak application by running the following:

    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
    

    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 the Up status of all the Greenlight services, which indicate 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.

    For example, for DOMAIN_NAME=xlab.bigbluebutton.org, GL_HOSTNAME=gl and KC_HOSTNAME=kc, Greenlight is accessible at http://gl.xlab.bigbluebutton.org/ and Keycloak at http://kc.xlab.bigbluebutton.org.

    If you receive a 502 Bad Gateway error, please wait a few seconds and refresh the page. If you see the 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 it is for testing purposes.

    Besides, Keycloak and some browser features on Greenlight are strictly available through HTTPS. For the security and the convenience of the users, it is recommended to follow the next steps to enable secure HTTPS access to Greenlight.

    To setup the certificates to work with Greenlight, see Certificates


    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.

    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.

    Once you’ve made this change, you should now be able to access the Admin Panel through the profile dropdown (just as it was in v2).