From Apis Networks Wiki

Overview

Core Ruby libraries are in /usr/lib/ruby/. Gem Ruby library and gems are under /usr/local/lib/. Why? You would install under /usr/local/lib/ because /usr/lib/ruby/ is hardlinked to the master filesystem (which is what the GEM_HOME environment variable does).

Don't forget to add the following code to the file named .bash_profile in $HOME:

GEM_HOME=/usr/local/lib/ruby/gems/1.8/
RUBYLIB=/usr/local/lib/ruby/site_ruby/1.8/
RUBY_CONFIG_OPTS="--prefix=/usr/local"
 
export PATH GEM_HOME RUBYLIB RUBY_CONFIG_OPTS

• GEM_HOME instructs gem where to look for RubyGems.
• RUBYLIB provides an additional search path to Ruby, i.e. first check /usr/lib/ruby/ and then check /usr/local/lib/ruby/site_ruby/1.8/
• RUBY_CONFIG_OPTS is what gets passed off to any configure script. Have you ever built an application from source and had to run ./configure? Those extra parameters you pass off, e.g. ./configure --prefix=/usr/local are defined by RUBY_CONFIG_OPTS. Gems that build from C code and install additional support files, such as rmagick, need this variable to install correctly.

Binaries installed via gem install will be installed under /usr/local/lib/ruby/gems/1.8/bin/. You can either add this location to your PATH variable by adding: PATH="$PATH:/usr/local/lib/ruby/gems/1.8/bin/" to .bash_profile or by creating a symbolic link for each file in /usr/local/lib/ruby/gems/1.8/bin/ to /usr/local/bin/. cd /usr/local/lib/ruby/gems/1.8/bin/ && ln -sf * ../../../../../bin/ will make the necessary symlinks.

Setup

Installation Guide

See Rails Quickstart

Apache Configuration

Ruby on Rails applications are invoked via the Web server, Apache. There are very few differences between conventional WEBrick setup and Apis Networks' Apache-FastCGI model.

When an application is normally fired up via WEBrick, <app name>/script/server -d -p 3000, the <app name>/public/ functions as the document root, the location from which all pages are served.

Apache follows the same setup, except your main document root is /var/www/html/, instead of <app name>/public/. Thus to emulate functionality, we need to link <app name>/public/ to /var/www/html/, SSH into the account and execute:

cd /var/www/
rm -rf html/
ln -s <app name>/public/ html
 

Where <app name> is the base directory of the application created via rails <app name>.

Caveat: If you're attempting to deploy an application as the main user, it must be located under /var/www/ and not the home directory, /home/username/ or anywhere else. This is due to suexec limitations with the primary user. Rails applications deployed as separate users don't encounter these problems, but have to go through some separate hoops. All of this is covered in the article about the magical and infamous suexec.

Setting up on a subdomain

The process for setting up a Rails application on a subdomain is very similar to the above. You have two options however:

The first is to set the subdomain (ex: myapp.mydomain.com) as the application. To do this, access your control panel and select "Add Subdomain". Fill in the name, select the owner, and choose the path. Using this method, you will want to select the public folder of your application as the 'Full Directory Path'. So for example, if you select 'myapp' as your subdomain name, you would choose your 'Full Directory Path' to be '/var/www/myapp/public/'. Just add your application. If you're creating your application from scratch, use the commandline, and from the '/var/www/' directory type 'rails <my application directory>' and Rails should do it's thing.

Caveat: At the time of this writing, the permissions required to run rails on the directory do not exist on directories created by Ensim's subdomain system. As such you will need to ask an admin for permissions on your directory if choose this method.

The second method is more similar to doing it for a root directory. Access your control panel and select "Add Subdomain". Fill in the name, select the owner, and choose the 'Full Directory Path'. So for example, if you select 'mysubdomain' as your subdomain name, you would choose your 'Full Directory Path' to be '/var/www/mysubdomain'. Next you'll need to use the commandline, and from the '/var/www/' directory type: rails my application directory (ex: rails myapp) and rails will build into that directory.

Please Note: If you are using this method, your subdomain folder and application folder must have different names. If you would like them to be one in the same, please use the first method. This is, of course, a matter of preference.

Once you have your two directories, you'll need to establish the link between them as with an application in the site root. Using our above example you'd enter the following at the commandline from the site root (/var/www/):

rm -rf mysubdomain/
ln -s myapp/public/ mysubdomain
 

This would establish the link to the application (myapp) to the subdomain (mysubdomain).

Changing Environment

To set your Rails application to the 'production' environment, edit the .htaccess file from <app name>/public/.htaccess add SetEnv RAILS_ENV production.

The FastCGI process will need to be restarted after switching environments. From the shell, run the following command as the user under which the Rails applications is running (typically the primary user):

kill -HUP $(ps -C dispatch.fcgi -o pid=)

You may receive an Operation not permitted response from the server; this is benign informing you that it cannot send signals to other Rails processes on the server.

Reloading FastCGI

Code is periodically updated every 30 minutes; however, to force an immediate refresh of the Rails library, touch the FastCGI dispatcher (dispatch.fcgi). More information is provided in the FastCGI section of the resource center.

Configuring SQL Access

See MySQL Manager or PostgreSQL Manager depending upon the SQL language used. Modifications should be done under <app name>/config/database.yml. See MySQL Manager for additional settings information for MySQL.

MySQL's socket is located under /var/lib/mysql/mysql.sock. For PostgreSQL use 127.0.0.1 as the host.

Avoiding idle process killing

Rails processes inactive for longer than 10 minutes are subject to a reaping process by FastCGI to conserve system resources. For a highly active site, it should never be reaped, but for smaller hobbyist sites, you are subject to the Rails process being killed until another page request is made. A work around is to setup a cronjob to wget a Rails page on your site. Doing so avoids the timeout length. For example, a good, minimal Cronjob looks a bit like:

*/8 * * * * /usr/bin/wget -O /dev/null http://*yourdomain*/*some Rails page*

This downloads a page (simulates a page request by a user), deletes the output (-O /dev/null) and is run every 8 minutes (*/8 * * * *). Setting up a command like this will keep the Rails application running during inactive periods while you work on developing the site.

Gem Management

How can I install additional gems?

Use the Package Manager component of apnscp esprit to install additional gems found on RubyForge. Alternatively you may install from the terminal with the gem install command.

gem install <gem name> -- --prefix=/usr/local

Note the -- --prefix=/usr/local following gem install. This is passed off to the optional configure script if it needs to build any binary files.