Ruby Rack App Hosting with RVM, Passenger 3, Capistrano, Git and Apache

Posted on 15 Nov 2010

This guide has been superseded by 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. The notable differences are using passenger 3 and system wide rvm.

At the time of writing, the latest versions of the software in use are:

  • RVM: 1.0.21, system wide
  • Ruby: 1.9.2-p0
  • Passenger: 3.0.0
  • Rails: 3.0.2
  • Capistrano: 2.5.19

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 System Wide Install

rvm is installed system wide as this is now the best practice for deployments. 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 -L http://bit.ly/rvm-install-system-wide )

In order for a user to use the system wide rvm installation the following must be setup:

  • User must belong to the rvm group - system wide installation requires the correct permissions
  • User must use the rvm load script in profile files - the location of the load script is different to user specific installs
  • User must not have ~/.rvm - a user specific install overrides a system wide one

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 system wide 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

Simply edit .bashrc and add the following line at the bottom:

[[ -s /usr/local/lib/rvm ]] && source /usr/local/lib/rvm

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 notes about requirements for installing the different rubies by running rvm notes. The list of packages at the time of writing had dependency conflicts which can be circumvented by removing libreadline5-dev.

To install the packages (requires sudo):

sudo apt-get install openssl curl git-core subversion autoconf \
                     build-essential bison zlib1g zlib1g-dev \
                     libssl-dev libxml2-dev libreadline5 libreadline-dev \
                     libreadline6-dev libsqlite3-0 libsqlite3-dev sqlite3

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-p0/gems/passenger-3.0.0/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-p0/gems/passenger-3.0.0
PassengerRuby /usr/local/rvm/wrappers/ruby-1.9.2-p0/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("~/.rvm/lib"))
require 'rvm/capistrano'
set :rvm_ruby_string, '1.9.2-p0'
set :rvm_type, :system

# 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

  desc "Symlink shared resources on each release - not used"
  task :symlink_shared, :roles => :app do
    #run "ln -nfs #{shared_path}/config/database.yml #{release_path}/config/database.yml"
  end
end

after 'deploy:update_code', 'deploy:symlink_shared'

Note: the above file supplies the rvm ruby version as 1.9.2-p0. 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 and previous articles then 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

Testing

View your website in your browser and ensure it is loading.

Comments

blog comments powered by Disqus
Fork me on GitHub