root/cherokee/trunk/doc/cookbook_ror.txt

== link:index.html[Index] -> link:cookbook.html[Cookbook]

Cookbook: Setting up Ruby on Rails
----------------------------------

Setting up a Rails application to run with Cherokee and FastCGI is not
only easy. It is also the best possible solution to manage the load
among one or many Rails servers, using an extremely efficient web
server to manage the web part and leaving as many free resources as
possible to Rails.

Of course you will need a working Rails installation for this to
succed. You can set this up easily. If you have Ruby and Ruby Gems
installed, you can directly install the 'Rails' gem like this:

----
# gem update --system
# gem install rails
----

Note that on Debian based systems you don't even need to install
Rubygems. There is already a package that will install every needed
dependency:

----
# apt-get install rails
----

The installation of the 'Rails' gem directly would also work, but note
that you cannot execute the first command because it is disabled by
default.

----
# gem update --system
ERROR:  While executing gem ... (RuntimeError)
    gem update --system is disabled on Debian. RubyGems can be updated \
    using the official Debian repositories by aptitude or apt-get.
----

Once you are done with that, you must deploy your Rails project:

----
$ rails example
----

You can do so wherever you want, but the usal recommended way of doing
this is by deploying it outside of your web root path and then
creating a symbolic link. This is simply to protect from exposure all
the files that do not need to be in your document root.

Assuming you deployed the `example` project in `/home/foo/example`,
and you have writing permissions to your web path, `/var/www`, simply
type:

----
$ ln -s /home/foo/example/public /var/www/example
----

Now you are ready to configure Cherokee. You only need to know that
you can spawn the FastCGI process using a script that is already in
your deployed project. In this case,
`/home/foo/example/script/process/spawner`.
We will be using the default parameters (3 instances starting at port
8000) but you can fine tune this using the many parameters provided by
the script.

The process is fairly simple. Set up a new rule for this new path and
manage it with the FastCGI handler.

.Common CGI options
Under `Common CGI options` make sure to check the `Error handler` box and
uncheck `Check file`. This is to prevent possible errors with the
`INFO_PATH` generation that can happen when an application, in this
case 'Rails', manages the whole subtree. This is mentioned in the
link:modules_handlers_cgi.html[Common CGI] section of the
documentation. It is a good idea to enable the `Error handler`
checkbox since it will help you determine if an error is associated
with your Ruby on Rails application or with Cherokee. This, however,
is not required.

image::media/images/cookbook_ror_common.png[Common CGI options]

.FastCGI specific
Under `FastCGI specific` make sure to add the hosts providing the
service. Do this by adding one or more
link:config_info_sources.html[Information Sources].

Note that, in the definition of the informaction source, you will have
to manually launch the `spawner` if you use a `Remote host` as
`Information source` instead of a `Local interpreter`.

You will simply have to add as many sources as desired, for instance
our example uses the default values to set up ports 8000 through
8002. These sources will be nicknamed *ror0*, *ror1* and *ror2*.

[grid="rows"]
`~~~~~~~~~~~~~~`~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
Host           , Interpreter
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
localhost:8000 , `/home/foo/example/script/process/spawner fcgi`
localhost:8001 , `/home/foo/example/script/process/spawner fcgi`
localhost:8002 , `/home/foo/example/script/process/spawner fcgi`
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

If any of those ports was not reachable, the `interpreter` command
would be launched and the fallen one would be reinstantiated.

Here is a snapshot to show the creation of *ror0*. The rest are
similar using the port variation detailed above.

image::media/images/cookbook_ror_fcgi.png[FastCGI specifics]

Once everything is done you can check if Rails  is really
working. Simply navigate to the path configured by your rule,
http://localhost/example/ for instance, and you should see some notes
about your recently created project.

image::media/images/cookbook_ror.png[Rails example]