bigbluebutton_rails 1.4.0 → 2.0.0

data/README.md

@@ -0,0 +1,416 @@
+# BigBlueButton on Rails [<img src="http://travis-ci.org/mconf/bigbluebutton_rails.png"/>](http://travis-ci.org/mconf/bigbluebutton_rails)
+
+[BigBlueButton](http://bigbluebutton.org) integration for Ruby on Rails 4.
+
+Features:
+
+* Allows multiple servers and multiple conference rooms.
+* Full API access using
+    [bigbluebutton-api-ruby](https://github.com/mconf/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](https://github.com/plataformatec/devise) and
+    [CanCan](https://github.com/ryanb/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}[https://code.google.com/p/bigbluebutton/wiki/ClientConfigura
+    tion]` feature.
+* Automatic detection of the user-agent to automatically trigger the [mobile
+    client](https://github.com/bigbluebutton/bbb-air-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
+    [TODO.md](https://github.com/mconf/bigbluebutton_rails/blob/master/TODO.md).
+
+
+## Supported versions
+
+This gem is mainly used with [Mconf-Web](https://github.com/mconf/mconf-web).
+You can always use it as a reference for verions of dependencies and examples of how to use the gem.
+
+
+### BigBlueButton
+
+The current version of this gem supports `all` the following versions of
+BigBlueButton:
+
+* 1.0
+* 0.9
+* 0.81
+* 0.8
+
+
+### Ruby
+
+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.
+
+### Rails
+
+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`](https://github.com/mconf/bigbluebutton_rails/tree/v1.4.0).
+
+### Database
+
+We recommend the use of MySQL in your application, since this gem is developed
+and tested using it.
+
+
+## Upgrade
+
+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](https://github.com/mconf/bigbluebutton_rails/wiki). See:
+
+* [Migrate to 1.4.0](https://github.com/mconf/bigbluebutton_rails/wiki/Migrate-to-1.4.0)
+* [Migrate to 1.3.0](https://github.com/mconf/bigbluebutton_rails/wiki/Migrate-to-1.3.0)
+
+
+## Installation
+
+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](https://github.com/mconf/bigbluebutton_rails/wiki/How-to:-Generators)
+
+#### Dependencies
+
+Since version 1.4.0, this gem depends on
+[Resque](https://github.com/defunkt/resque), and since 2.0.0 it also uses
+[Resque-scheduler](https://github.com/resque/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](http://redis.io/) 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](https://github.com/defunkt/resque) and
+[Resque-scheduler](https://github.com/resque/resque-scheduler) to learn more
+about them and how to use them in development or production.
+
+### Routes
+
+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:
+
+    /bigbluebutton/servers
+    /bigbluebutton/servers/my-server/new
+    /bigbluebutton/servers/my-server/rooms
+    /bigbluebutton/rooms
+    /bigbluebutton/rooms/my-room/join
+
+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
+    end
+
+It creates routes to the actions used to access a conference room, so you can
+allow access to webconference rooms using URLs such as:
+
+    http://myserver.com/my-community/room-name/join
+    http://myserver.com/user-name/room-name/join
+
+For more information see:
+
+* [How to: Routes](https://github.com/mconf/bigbluebutton_rails/wiki/How-to:-Routes)
+
+
+### 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}[https://github.com/mconf/bigb
+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
+      end
+
+      def bigbluebutton_role(room)
+        ...
+      end
+
+    end
+
+### 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
+
+* [How recordings work](https://github.com/mconf/bigbluebutton_rails/wiki/How-Recordings-Work)
+
+
+### 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](https://github.com/defunkt/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}[https://github.com/mconf/bigbluebutton_rail
+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
+
+* [How to: Integrate with Devise](https://github.com/mconf/bigbluebutton_rails/wiki/How-to:-Integrate-with-Devise)
+* [How to: Integrate with CanCan](https://github.com/mconf/bigbluebutton_rails/wiki/How-to:-Integrate-with-CanCan)
+
+
+## Contributing/Development
+
+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:
+https://github.com/thoughtbot/capybara-webkit/wiki/Installing-Qt-and-compiling
+-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](https://github.com/mconf/bigbluebutton_rails/wiki/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.
+
+* See more about testing [in our wiki page](https://github.com/mconf/bigbluebutton_rails/wiki/Testing).
+
+
+### 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.
+
+Run:
+
+    rake best_practices
+
+And look at the file `rails_best_practices_output.html` to see the tips.
+
+## License
+
+Distributed under The MIT License (MIT). See
+[LICENSE](https://github.com/mconf/bigbluebutton_rails/blob/master/LICENSE).
+
+## Contact
+
+This project is developed as part of Mconf (http://mconf.org).
+
+Mailing list:
+* mconf-dev@googlegroups.com
+
+Contact:
+* Mconf: A scalable opensource multiconference system for web and mobile devices
+* PRAV Labs - UFRGS - Porto Alegre - Brazil
+* http://www.inf.ufrgs.br/prav/gtmconf

data/Rakefile

@@ -7,7 +7,7 @@ require 'cucumber'
 require 'cucumber/rake/task'
 
 desc 'Default: run specs and features.'
-task :default => [:spec, :cucumber]
+task :default => [:spec]
 
 RSpec::Core::RakeTask.new(:spec)
 
@@ -15,8 +15,8 @@ desc 'Generate documentation.'
 RDoc::Task.new do |rdoc|
   rdoc.rdoc_dir = 'rdoc'
   rdoc.title    = 'BigBlueButton on Rails'
-  rdoc.rdoc_files.include('README.rdoc')
-  rdoc.rdoc_files.include('CHANGELOG.rdoc')
+  rdoc.rdoc_files.include('README.md')
+  rdoc.rdoc_files.include('CHANGELOG.md')
   rdoc.rdoc_files.include('lib/**/*.rb')
   rdoc.rdoc_files.include('app/**/*.rb')
 end
@@ -62,14 +62,12 @@ namespace :rails_app do
 end
 
 task :cucumber do
-  if File.exists? "features/"
-    puts "* Gem features"
-    sh "bundle exec cucumber features/"
-  end
+  # Disable all features that need the bot. It isn't working since BigBlueButton 0.81.
+  tags = "~@need-bot"
 
   puts "* Dummy app features"
   cd File.join(File.dirname(__FILE__), "spec", "rails_app")
-  sh "bundle exec cucumber features/"
+  sh "bundle exec cucumber features/ --tags #{tags}"
   cd File.dirname(__FILE__)
 end
 
@@ -84,9 +82,10 @@ namespace :spec do
     cd "spec/rails_app/"
     sh "bundle exec rails destroy bigbluebutton_rails:install"
     sh "bundle exec rails generate bigbluebutton_rails:install 0.0.4"
-    sh "bundle exec rails generate bigbluebutton_rails:install 0.0.5 --migration-only"
-    sh "bundle exec rails generate bigbluebutton_rails:install 1.3.0 --migration-only"
-    sh "bundle exec rails generate bigbluebutton_rails:install 1.4.0 --migration-only"
+    sh "bundle exec rails generate bigbluebutton_rails:install 0.0.5 --migration-only --force"
+    sh "bundle exec rails generate bigbluebutton_rails:install 1.3.0 --migration-only --force"
+    sh "bundle exec rails generate bigbluebutton_rails:install 1.4.0 --migration-only --force"
+    sh "bundle exec rails generate bigbluebutton_rails:install 2.0.0 --migration-only --force"
 
     sh "bundle exec rake db:drop RAILS_ENV=test"
     sh "bundle exec rake db:create RAILS_ENV=test"
@@ -95,9 +94,10 @@ namespace :spec do
 
     cd "../.."
     Rake::Task["spec"].invoke
-    Rake::Task["cucumber"].invoke
+    # Rake::Task["cucumber"].invoke
 
     cd "spec/rails_app/"
+    sh "bundle exec rails destroy bigbluebutton_rails:install 2.0.0 --migration-only"
     sh "bundle exec rails destroy bigbluebutton_rails:install 1.4.0 --migration-only"
     sh "bundle exec rails destroy bigbluebutton_rails:install 1.3.0 --migration-only"
     sh "bundle exec rails destroy bigbluebutton_rails:install 0.0.5 --migration-only"