{"id":22191808,"url":"https://github.com/bigbluebutton/bbb-app-rooms","last_synced_at":"2026-02-06T03:10:32.095Z","repository":{"id":39675673,"uuid":"141628101","full_name":"bigbluebutton/bbb-app-rooms","owner":"bigbluebutton","description":"Simple web applcation for providing BigBlueButton rooms through LTI using a bbb-lti-broker","archived":false,"fork":false,"pushed_at":"2026-01-22T05:30:34.000Z","size":1715,"stargazers_count":11,"open_issues_count":38,"forks_count":15,"subscribers_count":6,"default_branch":"master","last_synced_at":"2026-01-22T08:15:07.742Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":"","language":"Ruby","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"lgpl-3.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/bigbluebutton.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2018-07-19T20:33:53.000Z","updated_at":"2026-01-22T05:29:41.000Z","dependencies_parsed_at":"2024-02-20T21:40:30.024Z","dependency_job_id":"f0935bcc-14d7-4efb-90a3-24847a74fceb","html_url":"https://github.com/bigbluebutton/bbb-app-rooms","commit_stats":{"total_commits":315,"total_committers":10,"mean_commits":31.5,"dds":0.5047619047619047,"last_synced_commit":"b39927ba89f394ed2b940a6f3c00200075e32f3b"},"previous_names":[],"tags_count":87,"template":false,"template_full_name":null,"purl":"pkg:github/bigbluebutton/bbb-app-rooms","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/bigbluebutton%2Fbbb-app-rooms","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/bigbluebutton%2Fbbb-app-rooms/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/bigbluebutton%2Fbbb-app-rooms/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/bigbluebutton%2Fbbb-app-rooms/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/bigbluebutton","download_url":"https://codeload.github.com/bigbluebutton/bbb-app-rooms/tar.gz/refs/heads/master","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/bigbluebutton%2Fbbb-app-rooms/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":29147518,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-02-06T02:39:25.012Z","status":"ssl_error","status_checked_at":"2026-02-06T02:37:22.784Z","response_time":59,"last_error":"SSL_connect returned=1 errno=0 peeraddr=140.82.121.5:443 state=error: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2024-12-02T12:17:51.528Z","updated_at":"2026-02-06T03:10:32.078Z","avatar_url":"https://github.com/bigbluebutton.png","language":"Ruby","funding_links":[],"categories":[],"sub_categories":[],"readme":"\u003ch1\u003eHow to deploy the LTI Rooms Tool with the LTI Broker locally\u003c/h1\u003e\nThis is a tutorial for a local deployment of the rooms and broker apps as well as setting it up with moodle (or any other LMS).\n\n## Prerequisites\nIn order to successfully run the LTI applications, you must have the following prerequisites:\n- A BigBlueButton server \n- A domain name\n- A learning management system (admin privileges are required in order to add the application as an external tool)\n- [Docker](https://www.digitalocean.com/community/tutorials/how-to-install-and-use-docker-on-ubuntu-18-04) and [Docker-compose](https://docs.docker.com/compose/install/linux/) installed\n\n\n# Setup \u0026 Run\n\nYou have two options for running the LTI applications: \n1. [Using DockerHub Images.](##-Option-1:-Use-DockerHub-Images)\n2. [Cloning the repositories for GitHub.](##-Option-2:-Cloning-the-Repos-from-GitHub-(for-development))\n\nIf you simply want to run the application, go with option 1. Option 2 is for development purposes. \n\n\nIn both cases, you will need to first clone and setup [bbb-lti-run](https://github.com/jfederico/bbb-lti-run).\n\n\n## Setting up bbb-lti-run\n1. Clone the repo\n ```\ngit clone git@github.com:blindsidenetworks/bbb-lti-run.git\ncd bbb-lti-run\n```\n\n\n2. Edit the `.env` file located in the root of the project\n\n\n```\ncp dotenv .env\nvi .env\n```\n\n\nSet `HOST_NAME` to your domain name (the deployment endpoint). For example, ``` https://lti.\u003cJOHN\u003e.blindside-dev.com/ ```\n\n\n### Generating LetsEncrypt SSL Certificate Manually\n\n\nCreate your own SSL Letsencrypt certificates. If you are going to\nhave this deployment running on your own computer (or in a private VM), you\nneed to generate the SSL certificates with certbot manually by adding the\nchallenge to your DNS.\n\n\nInstall letsencrypt in your own computer\n\n\n```\nsudo apt-get update\nsudo apt-get -y install letsencrypt\n```\n\n\nMake yourself root\n\n\n```\nsudo -i\n```\n\n\nStart creating the certificates\n\n\n```\ncertbot certonly --manual -d lti.\u003cJOHN\u003e.blindside-dev.com --agree-tos --no-bootstrap --manual-public-ip-logging-ok --preferred-challenges=dns --email hostmaster@blindside-dev.com --server https://acme-v02.api.letsencrypt.org/directory\n```\n\n\nYou will see something like this\n```\n-server https://acme-v02.api.letsencrypt.org/directory\nSaving debug log to /var/log/letsencrypt/letsencrypt.log\nPlugins selected: Authenticator manual, Installer None\nObtaining a new certificate\nPerforming the following challenges:\ndns-01 challenge for gl.\u003cJOHN\u003e.blindside-dev.com\ndns-01 challenge for gl.\u003cJOHN\u003e.blindside-dev.com\n\n\n- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -\nPlease deploy a DNS TXT record under the name\n_acme-challenge.gl.\u003cJOHN\u003e.blindside-dev.com with the following value:\n\n\n2dxWYkcETHnimmQmCL0MCbhneRNxMEMo9yjk6P_17kE\n\n\nBefore continuing, verify the record is deployed.\n- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -\nPress Enter to Continue\n```\n\n\nCreate a TXT record in your DNS for\n`_acme-challenge.lti.\u003cJOHN\u003e.blindside-dev.com` with the challenge string as\nits value `2dxWYkcETHnimmQmCL0MCbhneRNxMEMo9yjk6P_17kE`\n\n\nCopy the certificates to your bbb-lti-run directory. Although `/etc/letsencrypt/live/`\nholds the latest certificate, they are only symbolic links. The real files must be copied too.\n\n\n```\ncd bbb-lti-run\nmkdir -p data/certbot/conf/archive\nmkdir -p data/certbot/conf/live\ncp -R /etc/letsencrypt/archive/lti.\u003cJOHN\u003e.blindside-dev.com \u003cYOUR ROOT\u003e/bbb-lti-run/data/certbot/conf/archive\ncp -R /etc/letsencrypt/live/lti.\u003cJOHN\u003e.blindside-dev.com \u003cYOUR ROOT\u003e/bbb-lti-run/data/certbot/conf/live\n```\n\n\nYay! You've set up bbb-lti-run. Now, you have 2 options for how to run the LTI apps:\n    \n1. [By pulling the images from DockerHub](#Option-1:-Use-DockerHub-Images)\n\n2. [By cloning the repos from GitHub (this setup is for development)](#Option-2:-Cloning-the-Repos-from-GitHub-(for-development))\n\n\n## Option 1: Use DockerHub Images\n1. In the .env file located at the root of bbb-lti-run:\n    -  Optionally, set the `DOCKER_REPO` environment variable to the repo from which you would like to pull the images ('bigbluebutton' is the default if this variable isn't set)\n    -  Optionally, set the `DOCKER_TAG` environment variable to the tag of the images you'd like to pull ('latest' is the default if this variable isn't set)\n        \n2. Set the environment variables for broker and rooms:\n    * Edit the `broker/.env` file and replace the following default values.\n\n\n        ```\n        cp broker/dotenv broker/.env\n        vi broker/.env\n        ```\n\n\n        | Variable | Description |\n        | --------- | --------- |\n        | **SECRET_KEY_BASE** | This is the Ruby On Rails secret key and must be replaced with a random one. You can generate a suitable secret using `openssl rand -hex 32`. |\n        | **RELATIVE_URL_ROOT** | This is the root of the project (ex. 'lti') |\n        | **DEFAULT_LTI_TOOL** | This one is used to set the default tool (currently the only tool available is rooms) |\n        | **URL_HOST** | Your domain name |\n        | **DATABASE_URL** | The URL of the database you are using (only set this if you are using a database outside of bbb-lti-run's postgres instance) |\n\n\n\n\n    * Edit the `rooms/.env` file and replace the following default values.\n\n\n                ```\n                cp rooms/dotenv rooms/.env\n                vi rooms/.env\n                ```\n\n\n        | Variable | Description |\n        | --------- | --------- |\n        | **SECRET_KEY_BASE** | This is the Ruby On Rails secret key and must be replaced with a random one. You can generate a suitable secret using `openssl rand -hex 32`. |\n        | **RELATIVE_URL_ROOT** | The relative root for Rooms, it is required as is (for now), and it is by default set to `apps` |\n        | **BIGBLUEBUTTON_ENDPOINT** | The BigBlueButton Endpoint to the server linked to this application. |\n        | **BIGBLUEBUTTON_SECRET** | The BigBlueButton Secret (this can be found by running `bbb-conf --secret` in the BBB server)  |                  \n        | **BIGBLUEBUTTON_MODERATOR_ROLES** | Specify which roles should be considered moderators in a BigBlueButton meeting. For example, Instructor,Faculty,Teacher,Mentor,Administrator,Admin |\n        | **OMNIAUTH_BBBLTIBROKER_SITE** | Should match the values set up for the broker URL_HOST\n        | **OMNIAUTH_BBBLTIBROKER_ROOT** | Should match the values set up for the broker RELATIVE_URL_ROOT\n        | **OMNIAUTH_BBBLTIBROKER_KEY** and **OMNIAUTH_BBBLTIBROKER_SECRET** | Choose whichever values you like for these. We will use the same values later in step 6 when adding the rooms app as a tool in the broker. |\n        | **DATABASE_URL** | The URL of the database you are using (only set this if you are using a database outside of bbb-lti-run's postgres instance) |\n\n\n3. In the bbb-lti-run root directory (`cd \u003cyour root\u003e/bbb-lti-run`), start the environment with the the command `docker compose up` (or `docker-compose up`, depending on your docker compose version)\n\n\n4. To test that the set up was successful once all the containers are running, visit the url you configured for your HOST_NAME. For ex.  ``` https://lti.\u003cJOHN\u003e.blindside-dev.com/ ``` . You will be taken to the BBB LTI Broker site. \n\n\n\n\n5. Now, it is time to add the rooms app as a tool in the broker. To do so, you'll need your **URL_HOST** and the following variables that you set in bbb-lti-run's rooms/.env file: \n**RELATIVE_URL_ROOT** , **OMNIAUTH_BBBLTIBROKER_KEY**, **OMNIAUTH_BBBLTIBROKER_SECRET**. Run the following commands with your respective values:\n        \n    ```\n    docker exec -t broker bundle exec rake db:keys:add[\u003cOMNIAUTH_BBBLTIBROKER_KEY\u003e,\u003cOMNIAUTH_BBBLTIBROKER_KEY\u003e]\n    \n    docker exec -t broker bundle exec rake db:apps:add[rooms,\u003cURL_HOST\u003e/\u003cRELATIVE_URL_ROOT\u003e/rooms/auth/bbbltibroker/callback, \u003cOMNIAUTH_BBBLTIBROKER_KEY\u003e,\u003cOMNIAUTH_BBBLTIBROKER_KEY\u003e]\n    ```\n        \n    For example, if your values were:\n    \n    ```\n    URL_HOST=https://lti.JOHN.blindside-dev.com\n    RELATIVE_URL_ROOT=apps\n    OMNIAUTH_BBBLTIBROKER_KEY=exampleKey\n    OMNIAUTH_BBBLTIBROKER_SECRET=exampleSecret\n    ```\n       \n    then you would run the following commands:\n    \n    ```\n    docker exec -t broker bundle exec rake db:keys:add[examplekey,exampleSecret]\n    docker exec -t broker bundle exec rake db:apps:add[rooms,https://lti.JOHN.blindside-dev.com/apps/rooms/auth/bbbltibroker/callback, exampleKey,exampleSecret]\n    ```\n\n\n6. Yay! Now you're ready to [add the rooms app to your LMS](#Configure-the-Rooms-app-in-your-LMS)!\n\n\n\n\n## Option 2: Cloning the Repos from GitHub (for development)\nThere are 2 additional repos you will need in order to run LTI:\n- [bbb-app-rooms](https://github.com/bigbluebutton/bbb-app-rooms): this application serves as the user interface for providing BigBlueButton rooms through LTI.\n- [bbb-lti-broker](https://github.com/bigbluebutton/bbb-lti-broker): The BBB LTI Broker is a Web Application that acts as a LTI Broker for connecting Tool Consumers with BigBlueButton Tools.\n\n\n1. After cloning the two repos, edit the .env files in each and replace the default values. \n\n    For the Broker: \n   \n    ```\n    cp bbb-lti-broker/dotenv bbb-lti-broker/.env\n    vi .env\n    ```\n\n\n    | Variable | Description |\n    | --------- | --------- |\n    | **SECRET_KEY_BASE** | This is the Ruby On Rails secret key and must be replaced with a random one. You can generate a suitable secret using `openssl rand -hex 32`. |\n    | **RELATIVE_URL_ROOT** | This is the root of the project (ex. 'lti') |\n    | **DEFAULT_LTI_TOOL** | This one is used to set the default tool (currently the only tool available is rooms) |\n    | **URL_HOST** | Your domain name |\n    | **DATABASE_URL** | The URL of the databse you are using (if you are following this guide exactly, this would be the database URL of the postgres docker container from bbb-lti-run). For example, `postgresql://postgres:password@\u003cyour ip\u003e:5432` |\n\n\n    For Rooms:\n    ```\n    cp bbb-app-rooms/dotenv bbb-app-rooms/.env\n    vi .env\n    ```\n\n    | Variable | Description |\n    | --------- | --------- |\n    | **SECRET_KEY_BASE** | This is the Ruby On Rails secret key and must be replaced with a random one. You can generate a suitable secret using `openssl rand -hex 32`. |\n    | **RELATIVE_URL_ROOT** | The relative root for Rooms, it is required as is (for now), and it is by default set to `apps` |\n    | **BIGBLUEBUTTON_ENDPOINT** | The BigBlueButton Endpoint to the server linked to this application. |\n    | **BIGBLUEBUTTON_SECRET** | The BigBlueButton Secret (this can be found by running `bbb-conf --secret` in the BBB server)  |                  \n    | **BIGBLUEBUTTON_MODERATOR_ROLES** | Specify which roles should be considered moderators in a BigBlueButton meeting. For example, Instructor,Faculty,Teacher,Mentor,Administrator,Admin |\n    | **OMNIAUTH_BBBLTIBROKER_SITE** | Should match the values set up for the broker URL_HOST\n    | **OMNIAUTH_BBBLTIBROKER_ROOT** | Should match the values set up for the broker RELATIVE_URL_ROOT\n    | **OMNIAUTH_BBBLTIBROKER_KEY** and **OMNIAUTH_BBBLTIBROKER_SECRET** | Choose whichever values you like for these. We will use the same values later in step 6 when adding the rooms app as a tool in the broker. \n        \n2. Create, migrate and seed the databases for both the rooms and broker: `rake db:create db:migrate`\n\n\n3. Now, it is time to add the rooms app as a tool in the broker. To do so, you'll need your **URL_HOST** and the following variables that you set in bbb-lti-run's rooms/.env file: \n**RELATIVE_URL_ROOT** , **OMNIAUTH_BBBLTIBROKER_KEY**, **OMNIAUTH_BBBLTIBROKER_SECRET**. Run the following commands with your respective values:\n    ```\n    rake db:apps:add[rooms,\u003cURL_HOST\u003e/\u003cRELATIVE_URL_ROOT\u003e/rooms/auth/bbbltibroker/callback, \u003cOMNIAUTH_BBBLTIBROKER_KEY\u003e,\u003cOMNIAUTH_BBBLTIBROKER_KEY\u003e]\n    ```\n\n\n    then, add the Add the key and secret to the keyset:\n    ```\n    rake db:keys:add[\u003cOMNIAUTH_BBBLTIBROKER_KEY\u003e,\u003cOMNIAUTH_BBBLTIBROKER_KEY\u003e]\n    ```\n         \n    For example, if your values are:\n    ```\n    URL_HOST=https://lti.JOHN.blindside-dev.com\n    RELATIVE_URL_ROOT=apps\n    OMNIAUTH_BBBLTIBROKER_KEY=exampleKey\n    OMNIAUTH_BBBLTIBROKER_SECRET=exampleSecret\n    ```\n    \n    then you would run the commands:\n    ```\n    rake db:apps:add[rooms,https://lti.JOHN.blindside-dev.com/apps/rooms/auth/bbbltibroker/callback, exampleKey,exampleSecret]\n\n    rake db:keys:add[\u003cOMNIAUTH_BBBLTIBROKER_KEY\u003e,\u003cOMNIAUTH_BBBLTIBROKER_KEY\u003e]\n    \n    ```\n\n\n4. Now it is time to run the applications! \n    - From the bbb-app-rooms directory, run `rails s -b 0.0.0.0 -p 3012`\n    - From the bbb-lti-broker directory, run `rails s -b 0.0.0.0 -p 3011`\n    - From the bbb-lti-run directory, run `docker compose up`\n        \n5. To test that the set up was successful once all the containers are running, visit the url you configured for your URL_HOST. For ex.  ``` https://lti.\u003cJOHN\u003e.blindside-dev.com/ ``` . You will be taken to the BBB LTI Broker site. \n\n\n6. Yay! Now you're ready to [add the rooms app to your LMS](#Configure-the-Rooms-app-in-your-LMS)!\n\n\n# Configure the Rooms app in your LMS\nThis process will depend on which LMS you are using. However, in all cases, you will need the LTI launch endpoint URL to configure your LMS. To get your LTI link, visit your broker site (ex. https://lti.JOHN.blindside-dev.com/). Then click 'config' in the top right. There, you will find the LTI launch endpoint.\n\nThe consumer_key and shared_secret are the same as the ones set in the rooms env. variables (as OMNIAUTH_BBBLTIBROKER_KEY and OMNIAUTH_BBBLTIBROKER_SECRET). When adding the tool, select LTI 1.0/1.1 (not 1.3). \n\nMake sure to select 'Force SSL' if your LMS provides you with that option (such as in Moodle). You may also face issues if your LMS's connection is not secure (make sure you are connecting over https).\n\n# Additional Environment Variables\nIn bbb-app-rooms, you may choose to configure these additional environment variables:\n| Variable | Description |\n| --------- | --------- |\n| **CACHE_ENABLED** | If enabled, caching will be used for optimizing requests to external servers. It is false by default. |\n| **BIGBLUEBUTTON_CHECKSUM_ALGORITHM** |  SHA algorithm to use for the checksum required by the BBB API |\n\n# Exceptions\n### The DOMAIN NAME is updated after the application starts\nIt is important to note that if the DOMAIN NAME is updated after the application was run, the launcher will have a reference to the old domain as for the callbacks when using an external authentication system. In such cases the easiest way to overcome the issue is to recreate the database.\n\n```\ndocker ps\n```\n\nWill return something like this:\n\n\n```\nCONTAINER ID        IMAGE                                 COMMAND                  CREATED             STATUS              PORTS                                      NAMES\n2642896703a1        nginx                                 \"/bin/bash -c 'envsu…\"   25 minutes ago      Up 25 minutes       0.0.0.0:80-\u003e80/tcp, 0.0.0.0:443-\u003e443/tcp   nginx\n7d1b913aad6e        bigbluebutton/bbb-app-rooms:latest    \"scripts/start.sh\"       25 minutes ago      Up 25 minutes       0.0.0.0:3002-\u003e3000/tcp                     rooms\nb552ed1b3db6        bigbluebutton/bbb-lti-broker:latest   \"scripts/start.sh\"       25 minutes ago      Up 25 minutes       0.0.0.0:3001-\u003e3000/tcp                     broker\na41613dfa428        postgres:9.5-alpine                   \"docker-entrypoint.s…\"   25 minutes ago      Up 25 minutes       0.0.0.0:5432-\u003e5432/tcp                     postgres\n```\n\n\nUse the CONTAINER_ID to execute terminal commands.\n\n\n```\ndocker exec -t broker DISABLE_DATABASE_ENVIRONMENT_CHECK=1 bundle exec rake db:drop\ndocker exec -t broker DISABLE_DATABASE_ENVIRONMENT_CHECK=1 bundle exec rake db:setup\n```\n\nIt may be necessary to interrupt docker-compose and execute a\n`docker compose down` and then `docker compose up` to clean up what is left","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fbigbluebutton%2Fbbb-app-rooms","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fbigbluebutton%2Fbbb-app-rooms","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fbigbluebutton%2Fbbb-app-rooms/lists"}