====== Ruby On Rails Easy Configuration with LiteSpeed Web Server Native ======

LSWS supports ruby on rails since version 2.2. The following is to setup ruby on rails with LSWS native mode. For shared hosting control panel environment with CloudLinux, please refer to [[litespeed_wiki:cloudlinux:enable_ruby_python_selector|this wiki]] to enable CloudLinux Ruby and Pathon selector.
===== Introduction =====

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 ([[https://www.litespeedtech.com/products/litespeed-sapi/ruby|Ruby LSAPI]])
  * LiteSpeed RubyRunner (Run CGI in persistent interpreter like mod_perl to perl)
  * FastCGI
  * Mongrel
  * CGI

In order to maximize the performance of a Rails application, LiteSpeed Technologies developed our own Ruby interface module using our LiteSpeed API protocol, also known as [[https://www.litespeedtech.com/lsapi/|LSAPI]]. 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 allows running plain Ruby CGI in a persistent interpreter without the cost of starting a new ruby process for each CGI script.  However, RubyRunner is not as fast as plain LSAPI script because Ruby interpreter has to do extra work to shield the run-time environment for each CGI script execution. RubyRunner is for running plain ruby CGI script unchanged. For Rails application, Ruby LSAPI is preferred. 

For running Rails application, Ruby LSAPI should give you the best performance as well as the the least configuration complexity. 



===== Requirements =====
Before you can setup RubyOnRails with LiteSpeed Web Server you should have finished the following steps:
  - LiteSpeed Web Server version 2.2 or higher. If you have LSWS <2.2, please visit the [[litespeed_wiki:other-ext-apps:ruby-rails-old|old Ruby on Rails wiki]].
  - Latest [[https://www.litespeedtech.com/products/litespeed-sapi/ruby|Ruby LSAPI]] for LiteSpeed. 
  - Have a working Ruby application installation, like [[http://mentalized.net/journal/2006/02/06/hello_ruby_on_rails_world/|this]] simple Hello World application.

===== Rails with Ruby LiteSpeed API =====

=== Part 1/2: Install Ruby LiteSpeed API extension ===
You can install Ruby LSAPI extension using RubyGem, just do 

<code>
gem install ruby-lsapi
</code>

Or, you can install from source code.

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

2) Unpack. 

<code>
tar zxvf ruby-lsapi.tar.gz
cd ruby-lsapi
</code>


3) Install Ruby LSAPi. 

<code>
ruby setup.rb config
ruby setup.rb setup
ruby setup.rb install
</code>

:!: Note: Please make sure do not mix manual and gem installation together, stick to one installation method only. The manual installation have higher priority and override the gem installation.


=== Part 2/2: LiteSpeed Server Config ===

1) Configure Server level Ruby/Rail settings under "Server => Rails" tab:

<code>
Ruby Path: /usr/local/bin/ruby <-- path to ruby executable 
Rails Environment: Production  <-- default rails env value
Max Connections: 10            <-- max number of concurrent connections
Run On Start Up: Yes           <-- spawn at server-start to decrease 1st page response time
</code>

2) Create a Virtual Host (vhost) within LiteSpeed. For this section, we will refer to this vhost as RubyVhost. If you want to run Rails dispatchers in SuEXEC mode, make sure to set "CGI Set UID Mode" to "DocRoot UID", otherwise, set it to "Server UID".

3) In RubyVhost's "Contexts" tab, create a new "Rails" Context:

<code>
URI: /    <-- arbitrary URL like '/blog/' can be used as long as your Rails app has been configured to work that way            
Location: /myrailapp/         <-- rails application root directory
Rails Environment: Production <-- overrides server level rails env default value
</code>

Note: **/myrailapp/ should be the root directory of the Rails application which contains the 'public/' sub-directory.**

4) "HT Access" should be disabled in RubyVhost's "General" tab if you don't need it for maximum performance. When using "Rails Context", dispatching rules within /myrailapp/public/.htaccess will be ignored.

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

Note: If your application has been setup properly with LSAPI, you should notice something in lsws/logs/stderr.log like:
   .../lsapi.so: warning: already initialized constant ENV
It is normal, and means that your rails application is powered by LSAPI. :-)
Since Ruby-LSAPI 2.0, this message has been gone.

5) (Optional but recommended) add rewrite rules. The following rules must be added to the RubyVhost's "Rewrite" tab, to fully enable caching. Using the standard Rails directive ''caches_page :action'' will leave .html files in your public directory, but the rules below are nessesary for LiteSpeed to pick those up.

<code>
RewriteRule ^(.*)/$ $1/index.html [QSA]
RewriteRule ^([^.]+)$ $1.html [QSA]
</code>

Also remember to "Enable Rewrite". Save your changes and restart the web server.

By default, LSWS uses 404 handler to forward a request to backend Rails application, it  will serve the static (cached) version of the page if available. If you want to have the page served by backend application based on request component other than URL, like a request header, you should use URL rewrite at virtual host level. For example, to serve a AJAX call with Rails application based on a special header, you can use a rewrite rule like:

  RewriteCond %{HTTP:X-Requested-With} !^$ 
  RewriteRule ^/      /dispatch.lsapi   [QSA,L]



=== Not Easy Enough? Virtual Host Template makes your life even easier ===

LiteSpeed Web Server 2.2 ships with a virtual host template "EasyRailsWithSuEXEC" dedicated for simple Rails Application configuration. The xml template is located in /lswsinstall/conf/templates/ directory. If you run one Rails application per virtual host and the root URL of your Rails application is "/", step 2-4 above can be replaced by adding a member to the template. For example, the same result can be reached if you add a member like this:

<code>
Virtual Host Name: RubyVHost
Domain: <the_vhost_domain_name> 
Aliases: <vhost_alias_if_any>
Virtual Host Root: /myrailapp/         <-- rails application root directory
</code>

Note: **/myrailapp/ should be the root directory of the Rails application which contains the 'public/' sub-directory.**

If you need to further customize the virtual host, just click the 'Instantiate' link to generate a dedicate vhost configuration for it.

Note: Rails applicationa configured via the template run in **SuEXEC** mode, under the **UID/GID** of the owner of **public/** folder of your rails application. You should pay attention to that.

Note: Under the Context tab for the virtual host don't forget to set your Rails Environment to either Production(default) or Development. 

**That's it folks. Super easy. Your Ruby on Rails application is now ready to rock the world.** 8-)