BigBlueButton integration for Ruby on Rails
Ruby HTML Gherkin Other
Fetching latest commit…
Cannot retrieve the latest commit at this time.
Failed to load latest commit information.
.gitignore Add .bundle/ to .gitignore Jan 28, 2014
.rspec Use spork-rails for tests Oct 4, 2013
.travis.yml Add redis service to travis Feb 14, 2017 Update Jul 22, 2016
LICENSE Add license information Aug 31, 2012 Add 1.0 as a supported version of BigBlueButton Apr 7, 2016

BigBlueButton on Rails

BigBlueButton integration for Ruby on Rails 4.


  • Allows multiple servers and multiple conference rooms.
  • Full API access using bigbluebutton-api-ruby.
  • Easy way to join conferences: simply create a room and call the join action.
  • Easy integration with authentication and authorization mechanisms, such as Devise and CanCan.
  • Support for recordings: meetings can be recorded, the list of recordings retrieved and recordings can be played.
  • Possibility to create private rooms, that require a password to join.
  • Deals with visitors (users that are not logged), allowing (or forbidding) them to join rooms.
  • Uses static meeting IDs generated as a globally unique identifier (e.g. 36mskja87-029i-lsk9-b96e-98278407e145-1365703324).
  • Stores a registry of meetings that happened and associates them with the recording that was generated for it (if any).
  • Allows rooms to be configured dynamically using the {config.xml}[ tion] feature.
  • Automatic detection of the user-agent to automatically trigger the mobile client when joining a conference from a mobile device.

Possible future features:

  • Limit the number of users per room and rooms per server.
  • Server administration (use bbb-conf, etc).
  • Pre-upload of slides.
  • See

Supported versions

This gem is mainly used with Mconf-Web. You can always use it as a reference for verions of dependencies and examples of how to use the gem.


The current version of this gem supports all the following versions of BigBlueButton:

  • 1.0
  • 0.9
  • 0.81
  • 0.8


Tested in rubies:

Requires ruby >= 1.9.3.

  • ruby-2.2 recommended
  • ruby-2.1
  • ruby-1.9.3 (last tested with p484)

Use these versions to be sure it will work. Other patches of these versions should work as well.


To be used with Rails 4 only. Currently tested with Rails 4.1.

Version 1.4.0 was the last one to support Rails 3.2. To use it, use the tag v1.4.0.


We recommend the use of MySQL in your application, since this gem is developed and tested using it.


When updating the gem to a newer version, there are usually extra steps you'll have to take in order to have the database migrated, the dependencies updated, and others. These steps are described in our wiki. See:


You can install the latest version of BigbluebuttonRails using RubyGems:

gem install bigbluebutton_rails

Or simply add the following line in your Gemfile:

gem "bigbluebutton_rails"

After installing, you need to run the generator:

rails generate bigbluebutton_rails:install

This generator will create the files needed to setup the gem in your application. You should take some time to open all the files generated and analyze them.

By default the gem will use the views it provides, but it is strongly recommended that you adapt them for your needs! The views provided are just an example of how they can be implemented in your application and they depend on jQuery (use the gem jquery-rails) and on a css file provided by this gem. You can easily generate the views and the css file in your application to later customize them with:

rails generate bigbluebutton_rails:views

To now more about the generators see How to: Generators


Since version 1.4.0, this gem depends on Resque, and since 2.0.0 it also uses Resque-scheduler.

These gems are used to run background jobs. The ones we have right now are: update the list of recordings, check for meetings that started or ended to update the database.

The gem already requires all dependencies, so you don't have to include them in your Gemfile. But you need to configure your application to use Resque and Resque-scheduler.

To do so, copy the following files to your application:

  • config/resque/resque.rake to your application's lib/tasks/;
  • config/resque/workers_schedule.yml to your application's config/.

The first is a rake task to trigger Resque and Resque-scheduler. The second is the scheduling of tasks used by Resque-scheduler. If you already use these gems in your application, you probably already have these files. So you can just merge them together.

To run Resque and Resque-scheduler you will need to run the take tasks:

QUEUE="bigbluebutton_rails" rake resque:work
rake resque:scheduler

These gems use redis to store their data, so you will need it in your server. If you're on Ubuntu, you can install it with:

apt-get install redis-server

Please refer to the documentation of Resque and Resque-scheduler to learn more about them and how to use them in development or production.


The routes to BigbluebuttonRails can be generated with the helper bigbluebutton_routes. See the example below:

bigbluebutton_routes :default

It will generate the default routes. You need to call it at least once and the routes will be scoped with 'bigbluebutton'. They will look like:


You can also make the routes use custom controllers:

bigbluebutton_routes :default, :controllers => {
  :servers => 'custom_servers',
  :rooms => 'custom_rooms',
  :recordings => 'custom_recordings'

To generate routes for a single controller:

bigbluebutton_routes :default, :only => 'servers'

You may also want shorter routes to access conference rooms. For that, use the option room_matchers:

resources :users do
  bigbluebutton_routes :room_matchers

It creates routes to the actions used to access a conference room, so you can allow access to webconference rooms using URLs such as:

For more information see:

Basic configuration

There are some basic assumptions made by BigbluebuttonRails:

  • You have a method called current_user that returns the current user;
  • The current_user has an attribute or method called "name" that returns his/her fullname and an attribute or method "id" that returns the ID.

If you don't, you can change this behaviour easily, keep reading.

BigbluebuttonRails uses the methods bigbluebutton_user and bigbluebutton_role(room) to get the current user and to get the permission that the current user has in the room, respectively. These methods are defined in {lib/bigbluebutton_rails/controller_methods.rb}[ luebutton_rails/blob/master/lib/bigbluebutton_rails/controller_methods.rb] and you can reimplement them in your application controller to change their behaviour as shown below.

class ApplicationController < ActionController::Base

  # overriding bigbluebutton_rails function
  def bigbluebutton_user
    current_user && current_user.is_a?(User) ? current_user : nil

  def bigbluebutton_role(room)


Updating the recordings

Since this task can consume quite some time if your server has a lot of recordings, it is recommended to run it periodically in the background. It is already done by the application if you are running Resque and Resque-scheduler properly. But this gem also provides a rake task to fetch the recordings from the web conference servers and update the application database.

The command below will fetch recordings for all servers and update the database with all recordings found:

rake bigbluebutton_rails:recordings:update

Updating the list of meetings

Meetings (BigbluebuttonMeeting models) in BigbluebuttonRails are instances of meetings that were held in web conference rooms. A meeting is created whenever the application detects that a user joined a room and that he's the first user. Meetings are never removed, they are kept as a registry of what happened in the web conference servers connected to BigbluebuttonRails.

The creating of these objects is done in background using a gem called resque. Whenever a user clicks in the button to join a meeting, a resque worker is scheduled. This worker will wait for a while until the meeting is created and running in the web conference server, and will then create the corresponding BigbluebuttonMeeting object.

To keep track of meetings, you have to run the resque workers (this is needed both in development and in production):

rake resque:work QUEUE='bigbluebutton_rails'

The list of meetings is also periodically synchronized using Resque-scheduler (see the sections above).

Associating rooms and servers

Rooms must be associated with a server to function. When a meeting is created, it is created in the server that's associated with the room. The association is done using the server_id attribute in BigbluebuttonRoom. So applications that use this gem can manage all the associations by simply setting this attribute.

By default, this gem automatically selects a server if one is needed and the room has no server yet. If a room already has a server, the gem will never change it.

To change this behavior, applications can override the method {BigbluebuttonRoom#select_server}[ s/blob/5decf3fa7767002303cf8bda524dcbeca0a9146c/app/models/bigbluebutton_room. rb#L413]. This method is called by all methods that trigger API calls, methods that need a server to work properly. It receives a parameter that indicates which API call will be sent to the server.

If the method returns a server, the server will be associated with the room. If the method returns nil, the room will maintain the server it had previously (if any).

One common use would be to override this method to always select a new server when a meeting is created (when the argument received is :create). This would allow the implementation of a simple load balancing mechanism.

Example application

If you need more help to set up the gem or just want to see an example of it working, check out the test application at spec/rails_app/!

See also


Fork this repository, clone your fork and start by installing the dependencies:

bundle install

Note: if you're getting an error installing capybara-webkit, most likely you need to install QT, see: -capybara-webkit

First copy spec/rails_app/config/database.yml.example to spec/rails_app/config/database.yml. It uses MySQL since this is the database recommended for the applications that use this gem. You have to set the appropriate password for your MySQL user.

Save spec/rails_app/features/config.yml.example as spec/rails_app/features/config.yml and edit it to set values for an existent BigBlueButton server. You will need it to run the integration tests. For more information see the page Testing in our wiki.

Prepare the rails_app used for tests:

rake rails_app:install
rake rails_app:db SERVER=my-server # select a server you defined in 'config.yml'
rake rails_app:populate            # to create fake data, optional

Run the tests:

rake spec
rake cucumber SERVER=my-server

Or simply:

rake SERVER=my-server

If you're adding migrations to the gem, test them with:

rake spec:migrations

Note: If you don't set the SERVER variable, the first server in config.yml will be used.

You can also start the test application and navigate to localhost:3000 to check it:

cd spec/rails_app/
rails server

If you need to keep track of meetings, run the resque workers with:

rake resque:work QUEUE='bigbluebutton_rails'

Develop. :)

If you want your code to be integrated in this repository, please fork it, create a branch with your modifications and submit a pull request.

Test Coverage

Coverage is analyzed by default when you run:

rake spec

Run it and look at the file coverage/index.html.

Best Practices

We use the gem rails_best_practices to get some nice tips on how to improve the code.


rake best_practices

And look at the file rails_best_practices_output.html to see the tips.


Distributed under The MIT License (MIT). See LICENSE.


This project is developed as part of Mconf (

Mailing list: