WebROaR User Guide

1. Introduction

WebROaR is an application server that makes deployments of ruby web applications extremely simple. It provides an integrated solution to view the run time performance numbers and email notifications in case any exceptions occur in any of the deployed applications.

1.1. Key Features

Maximum Performance.
Simplified Deployment.
Runs Ruby on Rails™ as well as Rack compliant applications.
Run Multiple Applications Simultaneously.
Implements HTTP/1.1 grammar as per RFC 2616 including support for persistent, and chunked requests.
Intelligent load balancing and dynamic reaping of stuck ruby processing instances.
Provides run time performance data for the deployed applications.
Generates notifications in case any exceptions occur in any of the deployed applications.
SSL support.

3. Install

3.1. Prerequisites

ruby 1.8.x or 1.9.x
ruby 1.8-dev or 1.9-dev
openssl ruby extension (On Ubuntu/Debian it is available as libopenssl-ruby1.X)
zlib ruby extension
rubygems
C build tools (gcc etc) (e.g. build-essential on Ubuntu, Xcode on MacOS)
libsqlite3
libsqlite3-dev
gnutls 2.4.1 or later (Only necessary in case SSL support is required)
gnutls-dev 2.4.1 or later (Only necessary in case SSL support is required)

Ruby Shared Library

The server needs the shared library - libruby.so to run the ruby web applications.

If you are building ruby from source, please ensure you pass the flag —enable-shared while executing its ./configure script.

3.2. Procedure

WebROaR can installed using the following commands:

gem sources -a http://gems.github.com
sudo gem install webroar
sudo webroar install

SSL Support

In case you would like to setup SSL support for the server, use the following command line switch with sudo webroar install command mentioned above.

sudo webroar install --ssl-support

Configure further SSL options in the server's admin panel http://<yourservername>:<port>/admin-panel/configuration

After restarting the server, admin panel would now also be accessible over SSL. https://<yourservername>:<port>/admin-panel

Or if you like living in the fast lane, you can install the edge version giving the following commands:

git clone git://github.com/webroar/webroar.git
cd webroar
sudo rake install

SSL Support

To build with SSL support, use the following additional switch with the sudo rake install command:

sudo rake install ssl=yes

Configure further SSL options in the server's admin panel http://<yourservername>:<port>/admin-panel/configuration

After restarting the server, admin panel would now also be accessible over SSL. https://<yourservername>:<port>/admin-panel

3.3. Troubleshooting

It is suggested that rubygems software should be setup correctly beforehand, and you should be successfully able to access and use the already installed gems. (If you use Ubuntu, you might be able to relate to this point better.)

In case auto-installation of dependent gems fails (due to some prehistoric rubygems version or any other reason), you can install the following dependent gems individually first:
```
calendar_date_select, rack, rake, rspec, sqlite3-ruby, starling-starling
```
After successful installation of the webroar gem, any errors that occur during the setup are saved to the install.log created in the installed gem's directory. This can be used to troubleshoot the issues, if any.
All run time logs for the server and the deployed applications can be found in /var/log/webroar.

3.4. Setting up database for server admin panel

The server's admin panel itself is a Ruby on Rails™ web application, and by default uses sqlite as it's database. You can edit admin_panel/config/database.yml to setup a database of your liking and follow it up by running these commands from the admin_panel directory.

rake db:create
rake db:migrate

admin_panel directory would be present under the server's rubygem directory.

4. Usage

Start/Stop/Restart WebROaR:

sudo webroar start
sudo webroar stop
sudo webroar restart

Start/Stop/Restart a deployed application:

sudo webroar start <Application Name>
sudo webroar stop <Application Name>
sudo webroar restart <Application Name>

You can stop the admin panel application of the server any time, to conserve resources and ensure better security.

sudo webroar stop "Admin Panel"

To start it whenever you want, use the following command:

sudo webroar start "Admin Panel"

Please note that analytics data and exceptions are still captured by the server even when the admin panel is stopped.

5. Deploying applications

If the server got installed successfully, you should be able access it's admin panel using the link:
http://<yourservername>:<port>/admin-panel

You can log in with the username: admin and password that you had entered during server installation. Deploy the ruby web application of your choice accessing the Configuration link of the admin panel.

You do "not" need to restart the server when you deploy a new application. The application starts up automatically after deployment.

5.1. Rack applications (other than Rails)

To deploy any Rack based application (other than Rails) the following are required in it's root directory:

public folder containing static files like images and stylesheets
config.ru - the Rackup file for starting the application. This file must contain the complete logic for initializing the application.

Here are some examples of the Rackup files:

Merb

  require 'rubygems'
  require 'merb-core'
  Merb::Config.setup(:merb_root   => ENV['APP_ROOT'],
                     :environment => ENV['APP_ENV'],
                     :path_prefix => ENV['APP_BASE_URI'])
  Merb.environment = Merb::Config[:environment]
  Merb.root = Merb::Config[:merb_root]
  Merb::BootLoader.run
  run Merb::Rack::Application.new

Sinatra

  require 'rubygems'
  require 'rack'
  require 'sinatra'
  set :env, ENV['APP_ENV'] || :production
  set :raise_errors, true
  run Sinatra::Application

You can use following environment variables in config.ru to access the few application configuration parameters given at a time of application deployment in WebROaR.

ENV['APP_ROOT'] - To get the application root
ENV['APP_ENV'] - To get the application environment
ENV['APP_BASE_URI'] - To get the baseuri

6. Accessing run time statistics

For those applications whose Analytics are Enabled in their configuration, the following graphs are available under the Analytics link of the admin panel.

URL Breakdown
Most Time Consuming URLs
URL Hits
Slowest URLs
Top Database Consuming URLs
Percentage Time Spent in Database Layer
Average Response Time
Peak Requests in Second
Percentage CPU Utilization
Physical Memory Utilization

Additionally, CPU and Physical Memory usage graphs for the entire server are also available.

Currently, Analytics are only supported for Ruby on Rails™ applications. Also, after a specific request has been processed by the server, it takes about a minute for it’s data to show up in the graphs.

7. Exception Tracking and Notifications

Any exceptions that occur in any of the deployed application are captured by the server. An email notification is also sent out immediately with details of the exception, if the mail settings have been configured in the admin panel.

All the exceptions can be seen under the Exceptions link of the server admin panel.

Currently, this feature is only supported for Ruby on Rails™ applications. Also, it takes about a minute for an exception to show up in the Admin Panel after it has occurred.

9. Test Suite

If you are a programmer and wish to play around with the server's code, you might like to use it's test suite to test the robustness of your changes.

It can be run using the following command:

sudo webroar test

We execute this suite on our nightly builds and it currently has the following tests:

Unit Tests
Functional Tests
Admin-Panel Tests
Load Test I - Continuous run
Load Test II - Random sleep interval run
Build Tests