Ruby On Rails Detailed Step by Step Manual Configuration

This tutorial is outdated, please use Ruby on Rails Easy Configuration or Rails Shared Hosting Configuration

LiteSpeed web server is one of the best and easiest platform for large scale Ruby On Rails application deployment. There are five options to setup Rails application with LiteSpeed server:

• Ruby LiteSpeed API (Ruby LSAPI)
• LiteSpeed RubyRunner (Run CGI in persistent interpreter like mod_perl to perl)
• FastCGI
• Mongrel
• CGI

Pure CGI mode is not recommended as it is plainly slow. FastCGI is much better as the ruby interpreter stay persistent, however, the ruby FCGI module does not support persistent FCGI connection, which does not bring the best performance out of LiteSpeed's FastCGI interface.

Mongrel is a fast HTTP server for ruby, it is much faster than WEBrick comes with Rails, but still pretty slow comparing to web servers written in C/C++. Rails running under mongrel has comparable performance to Rails running as FastCGI, just slightly slower. Mongrel is easy to use as it does not require extra configuration, just start it under the root directory of your Rails application. However, its performance on serving static content is poor, so it is better to have a high performance web server sitting in front of mongrel for that job. Mongrel has another weakness is that, you need to start multiple Mongrel instances to take advantage of multiple CPU in a SMP server, which may complicate the installation for high performance environment. With LiteSpeed's reliable high performance load balancing reverse proxy interface, LiteSpeed web server can be placed in front of either one mongrel or a mongrel cluster, let Mongrel serve dynamic pages generated by Rails and serving static pages cached in file system by Rails.

In order to maximize the performance of a Rails application, we developed our own Ruby interface module using our LiteSpeed API protocol, LiteSpeed API, or LSAPI, is a highly optimized IPC protocol between LiteSpeed web server and a standalone process, which yields the best possible performance. LiteSpeed RubyRunner is an add-on to Ruby LiteSpeed API, which allow running plain Ruby CGI under a persistent interpreter, it makes ruby CGI runs much faster, however it is not as fast as plain LSAPI CGI as ruby interpreter has done extra work to insulate the run-time environment of each CGI execution.

LiteSpeed Web Server 2.2 and above provides a much easier way to configure a Rails application, which is highly recommended for simple Rails deployments, new wiki tutorial is here. If you are interested in knowing how to hook up LiteSpeed web server with a Rails application step by step, read on.

Before you can setup RubyOnRails with LiteSpeed Web Server you should have finished the following steps:

1. Latest LiteSpeed Web Server has been installed (Very easy, just follow the document)
2. RubyOnRails has been installed (Just follow instructions at http://weblog.rubyonrails.org/2017/3/20/Rails-5-1-rc1/
3. Have a working Ruby application installation, such as a simple Hello World application like this one.

You can install Ruby LSAPI extension using RubyGem, just do

gem install ruby-lsapi

Or, you can install from source code.

1) Download Ruby LSAPI from https://www.litespeedtech.com/index.php/products/litespeed-sapi/download.

2) Unpack.

tar zxvf ruby-lsapi.tar.gz
cd ruby-lsapi

3) Install Ruby LSAPI.

ruby setup.rb config
ruby setup.rb setup
ruby setup.rb install

4) Copy Ruby dispatch script for lsapi to the public folder of Ruby application. Note that dispatch.lsapi must have executable permission privilege for the litespeed server user.

cp rails/dispatch.lsapi /myrailapp/public/dispatch.lsapi

Note: When installed using RubyGem, dispatch.lsapi should be under the ruby library directory, on our test server it is

/usr/local/lib/ruby/gems/1.8/gems/ruby-lsapi-1.3/rails/dispatch.lsapi

1) Create a Virtual Host (vhost) within LiteSpeed. For this howto, we will refer to this vhost as RubyVhost.

2) If the Rails application is served from “Document Root”, set RubyVhost's “Document Root” to your rails application's “public” directory.

/myrailapp/public/

If the Rails application need to be mounted under a URI like “/typo/”, you need to create a static context pointing to the “public” directory.

URI: /typo/
Location: /myrailapp/public/

3) “HT Access” should be disabled in RubyVhost's “General” tab if you don't need that. There are rewrite rules in /myrailapp/public/.htaccess for dispatching requests, you may need to comment out those rules if you let LiteSpeed handle dispatching internally when .htaccess support is turned on. So we recommend to turn it off if you don't really need that.

Allow Override: None <-- make sure only "none" is checked or nothing is checked

4) Create a new external application definition under RubyVhost's “External Applications” tab.

Type: LSAPI App
Name: RubyRailsLSAPI 
Address: uds://tmp/lshttpd/rubyrailslsapi.sock
Max Connections: 10 <-- max concurrent connections

Environment:

RAILS_ENV=production   <-- use "development" for development environment
LSAPI_CHILDREN=10 <-- note that LSAPI_CHILDREN should equal 'Max Connections'

Persistent Connection: Yes <-- only LiteSpeed Ruby LSAPI provides persistent connections to rails.
Command: /myrailapp/public/dispatch.lsapi
Instances: 1 

5) Create a LSAPI context for dispatcher.

URI: /dispatch.lsapi  <-- could be any URL you wish, just make sure the same URL is reference later on.
Handler Type: LiteSpeed API
Handler Name: [VHost Level]: RubyRailsLSAPI <-- the external application we created.

This method can support multiple Rails application under one virtual host, just define a external application and LSAPI context for each application.

6) There are two options this step, one is using a 404 handler, another one is to use rewrite rules. Using 404 handler is more efficient. For one Rails per virtual host setup. You can create a new “Custom Error Pages” handler in in RubyVhost's “General” tab.

Error Code: 404 Not Found
URL: /dispatch.lsapi

For multiple rails per virtual host setup, you need to add a 404 handler in the static context defined in setup 2, by adding following to “Apache Style configurations”

ErrorDocument 404 /dispatch.lsapi   <-- must be the context URI defined in step 5

To use rewrite rule for this purpose, rewrite rules can be configured at virtual host level for single Rails, or at context/.htaccess level for multiple Rails setup.

For rewrite rules at virtual host level

RewriteRule ^/$ /index.html [QSA]
RewriteRule ^/([^.]+)$ /$1.html [QSA]
RewriteCond %{REQUEST_FILENAME} !-f
RewriteRule ^/(.*)$ /dispatch.lsapi [QSA,L] <-- must matches context URI in step 5

For rewrite rules at context or .htacess level

RewriteRule ^$ index.html [QSA]
RewriteRule ^([^.]+)$ $1.html [QSA]
RewriteCond %{REQUEST_FILENAME} !-f
RewriteRule ^(.*)$ dispatch.lsapi [QSA,L]   <-- must matches context URI in step 5

OK, your Rails applications are ready to roll!