Rails 3.1 / Rack App Hosting with RVM, Passenger 3, Capistrano, Git and Apache

This guide supersedes a number of earlier guides, providing the details to get up and running with a rack based application from a basic ubuntu server VPS. It is a walkthrough of the steps taken, and it is advisable to first read the installation instructions provided by the software authors.
At the time of writing, the latest versions of the software in use are:

• RVM: 1.9.0
• Ruby: 1.9.2-p290
• Passenger: 3.0.9
• Rails: 3.1.1
• Capistrano: 2.9.0

You may need to alter the versions in the steps below as some commands and paths contain explicit versions. The server used for hosting in the guide is an Ubuntu Lucid VPS, so tailor the steps to your platform accordingly. Also, substitute domainname, hostname and appname as appropriate for your environment.

RVM Multi User Install

RVM can be installed for multiple users by installing as root. This allows installations to be shared across different users, although different users can use which ever version they wish.
Log in as root and install using the preferred script:

bash < <(curl -s https://raw.github.com/wayneeseguin/rvm/master/binscripts/rvm-installer) 

In order for a user to use the multi user RVM installation the must belong to the rvm group. Also check that they do not have a ~/.rvm directory as this takes precedence over the multi user install for that user.

Create Passenger User

It is a good idea to create a passenger user on the server to install services as so that it is isolated from other users. You can also deploy your applications using this user. The passenger user needs sudo rights for installing packages using apt-get and running the passenger install script, and needs to be a member of the rvm group to use the multi user install.

sudo adduser passenger
sudo usermod -G passenger,www-data,sudo,rvm passenger
su - passenger 

You can remove the sudo right after completing the installation using the following:

sudo usermod -G passenger,www-data,rvm passenger

Generate a key pair for ssh too. On your client machine, create a key and use a string pass phrase:

ssh-keygen -v -t rsa -f passenger@domainname -C passenger@domainname 

This will create a private key called passenger@domainname and a public key called passenger@domainname.pub. Keep these somewhere safe.
You can register the public key into authorized_keys to allow key based ssh authentication. Run the following on your client machine:

scp passenger@domainname.pub passenger@hostname:~/.ssh/authorized_keys

Depending on the client and your preference, you can either enter the passphrase for you private key each time you connect, or run ssh-agent and register the key using ssh-add. To register the private key into your ssh agent on your client machine run the following and enter the passphrase when prompted:

ssh-add passenger@domainname 

You should now be able to ssh to the server without being challenged for the password, e.g:

ssh passenger@hostname

Passenger RVM Configuration

Note: if you previously had RVM installed as a single user you need to remove the old source line for $HOME/.rvm/scripts/rvm and move (or delete) the .rvm directory so that the system wide installation is picked up instead.
Log out and log in again as passenger to ensure the scripts work as expected. You can test RVM is available correctly by running:

type rvm | head -n1

You should then see the following output:

rvm is a function 

You can view the requirements for installing the different rubies by running rvm requirements.
To install the packages (requires sudo):

sudo apt-get install build-essential openssl libreadline6 libreadline6-dev curl git-core zlib1g zlib1g-dev libssl-dev libyaml-dev libsqlite3-0 libsqlite3-dev sqlite3 libxml2-dev libxslt-dev autoconf libc6-dev ncurses-dev automake libtool bison subversion

To install ruby 1.9.2:

rvm install 1.9.2
rvm use --default 1.9.2 

You can can now verify the ruby version and install some gems, e.g.:

ruby -v
gem install bundler rails

Passenger

Passenger is very easy to install. RVM provides some instructions specifically for passenger.
Install the gem and run the installation script. It will tell you what dependencies you are missing and how to install them:

gem install passenger
passenger-install-apache2-module 

Passenger provides some instructions on how to configure apache. I like to treat passenger as a mod for apache, allowing it to be enabled and disabled as required through the a2enmod and a2dismod commands respectively.
To enable passenger, create /etc/apache2/mods-available/passenger.load with the following contents:

LoadModule passenger_module /usr/local/rvm/gems/ruby-1.9.2-p290/gems/passenger-3.0.9/ext/apache2/mod_passenger.so

and /etc/apache2/mods-available/passenger.conf with the following contents:

PassengerRoot /usr/local/rvm/gems/ruby-1.9.2-p290/gems/passenger-3.0.9
PassengerRuby /usr/local/rvm/wrappers/ruby-1.9.2-p290/ruby

then enable the module and restart apache:

sudo a2enmod passenger
sudo /etc/init.d/apache2 restart

Apache

Each rack/rails application is made available through a virtual host directive in the apache configuration. The recommended way to do this is to create a file named after the site, e.g. domainname in /etc/apache2/sites-available and then enable and disable the site as required using the a2ensite and a2dissite commands respectively.
I prefer to put all web applications in /var/www and have users be able to create applications if they are a member of www-data:

sudo mkdir /var/www
sudo chown www-data:www-data /var/www
sudo chmod g+w /var/www

Hello World rack app

I find it useful to have a simple Hello World rack application to verify the rvm and passenger installation. The application can be run as a subdomain to allow testing and can be enabled and disabled as desired.
Create the necessary directory structure for a rack application:

cd /var/www
mkdir hw.domainname
cd hw.domainname
mkdir public
mkdir tmp 

Create /var/www/hw.domainname/config.ru with the following contents:

app = proc do |env|
  [200, { "Content-Type" => "text/html" }, ["hello, world"]]
end
run app 

Create /etc/apache2/sites-available/hw.domainname with the following contents:

<VirtualHost *:80>
    ServerName hw.domainname
    DocumentRoot /var/www/hw.domainname/public
    <Directory /var/www/hw.domainname/public>
        AllowOverride all
        Options -MultiViews
    </Directory>
</VirtualHost>

Enable the site, and then view it in your browser:

sudo a2ensite hw.domainname
sudo /etc/init.d/apache2 reload

This can then be disabled and reenabled if needed for debugging any issues at a later date:

sudo a2dissite hw.domainname
sudo /etc/init.d/apache2 reload

Rails app

You now need to create a virtual host for the rails app so that apache can handle the requests and pass off to passenger.
Create the necessary directory structure for a rails application (assuming its running as the domainname):

cd /var/www
mkdir domainname

Create /etc/apache2/sites-available/domainname with the following contents:

<VirtualHost *:80>
    ServerName domainname
    DocumentRoot /var/www/domainname/current/public
    <Directory /var/www/domainname/current/public>
        AllowOverride all
        Options -MultiViews
    </Directory>
</VirtualHost>

Enable the site, although there is nothing there to view until we have deployed it:

sudo a2ensite domainname
sudo /etc/init.d/apache2 reload

Capistrano

The following steps should be performed on your client machine to capify an existing rails application and deploy it.

Configuration

Make sure you have capistrano installed:

gem install capistrano

Initialise the rails application:

cd ~/dev/appname
capify .

This will generate some files, along with a sample config/deploy.rb. Replace the file contents with the following, using suitable values where applicable.

# RVM bootstrap
$:.unshift(File.expand_path('./lib', ENV['rvm_path']))
require 'rvm/capistrano'
set :rvm_ruby_string, '1.9.2-p290'

# bundler bootstrap
require 'bundler/capistrano'

# main details
set :application, "domainname"
role :web, "domainname"
role :app, "domainname"
role :db,  "domainname", :primary => true

# server details
default_run_options[:pty] = true
ssh_options[:forward_agent] = true
set :deploy_to, "/var/www/domainname"
set :deploy_via, :remote_cache
set :user, "passenger"
set :use_sudo, false

# repo details
set :scm, :git
set :scm_username, "passenger"
set :repository, "git@gitserver:domainname.git"
set :branch, "master"
set :git_enable_submodules, 1

# tasks
namespace :deploy do
  task :start, :roles => :app do
    run "touch #{current_path}/tmp/restart.txt"
  end

  task :stop, :roles => :app do
    # Do nothing.
  end

  desc "Restart Application"
  task :restart, :roles => :app do
    run "touch #{current_path}/tmp/restart.txt"
  end
end

Note: the above file supplies the rvm ruby version as 1.9.2-p290. It is advisable to be specific about the version here as if this were 1.9.2 and a newer ruby version is available you may start to receive errors in the capistrano deployment.

Deployment

The first time you deploy to the server you should run the deployment setup task:

cap deploy:setup

Thereafter you can deploy using:

cap deploy

Or if you have database migrations to run then use:

cap deploy:migrations

You may get some strange errors or failures when deploying. If you have followed the steps I have mentioned in this guide then hopefully you shouldn’t have many problems. Common problems are:

• wrong permissions of /var/www
• wrong permissions of passenger user
• not having rvm installed for passenger user
• not having the basic gems required to use capistrano on the server, simply install them as the passenger user