Setting up Ruby on Rails and Using Capistrano to Deploy Ruby on Rails Applications to Media Temple Dedicated Virtual Server 3.0

Why Another Rails Deployment Tutorial?

You’re right, there are already a bunch out there, some of them really good. Media Temple even has one for their Dedicated Virtual Server 2.0, though it’s a litle out-of-date and somewhat incomplete toward the end. I wanted to fill in the gaps until MT releases an updated article in their knowledge base.

Why Not Use Mongrel Clusters Instead of FastCGI?

The current preferred method for deploying Ruby on Rails apps is to use Apache, Pound, or some other type of reverse-proxy to pass HTTP requests to a cluster of Mongrel web servers.

The problem? Media Temple lets you manage your dedicated virtual server using Plesk 8.1, which is overall a really good way to do things. The core web server services (Apache, MySQL, PHP, among others) are managed and updated by Plesk, which is where the issue lies. Apache 2.0.52 comes installed, which is not compatible with the mod_proxy_balancer module used by the most common Mongrel setup. Apache 2.2 is needed to use that.

You could compile Apache 2.2 on your dedicated virtual to take advantage of mod_proxy_balancer, but this will drop you out of MT’s Update Option Program, which basically means you’re left to do every security update and version upgrade on your own. You’re free to go that route, but I’m not ready to opt-out of the UOP just yet.

If you want to stay eligible for Media Temple’s UOP, you can also try using Apache 2.0 as a Mongrel frontend with the older mod_proxy module or hacking together a homemade proxy with a randomizer and a text file. If you want to keep it relatively simple for now though, I’d stick with the officially supported FastCGI method until Apache 2.2 is officially supported on the Dedicated Virtual Servers.

Assumptions

I’m going to assume a few things in this how-to. Call it an “opinionated tutorial” if you’d like:

1. You know your way around the command-line shell, particularly bash.
2. You already know how to use a text editor like vim or emacs and will use it to modify your text files on the web server.
3. You’re using Subversion, CVS, or some other source management system to keep track of your code. This is a good practice on its own, but it’s a requirement for the next assumption.
4. You’re going to use Capistrano to automate the deployment of your Rails application and that it’s already installed on your local development machine. If you’re not using it already, you should be. Trust me.

Before You Start

Before you do anything else, make sure you have the following ready on your DV server:

1. Developer Tools - Media Temple staff will need to install the compliers and other tools necessary to build programs from source. Submit a support ticket to request this.
2. Root access - You’ll need root access enabled before compiling any programs. Submit a support ticket to Media Temple to request this.
3. A domain account created in Plesk with mod_fcgid support enabled - You can do this easily in Plesk using the control panel. Make sure your domain user has shell access and that a MySQL database has been created.

Optional, but recommended: At this point, it’s also a good idea to give your domain account’s user sudo rights, especially if Capistrano will be using it to automate your application deployments. To do this, issue the visudo command when you’re logged in as root then add a new line so it looks something like this:

root ALL = (ALL) ALL
<username> ALL = (ALL) ALL

1. Login to the server via SSH as root

You’ll need root access in order to continue, so login with that account now.

2. Download compile and install the latest version of Ruby

At the time of writing this, the current version of Ruby is 1.8.5. You can always find the latest supported version by visiting the Ruby on Rails download page.

cd /usr/local/src
wget http://ftp.ruby-lang.org/pub/ruby/1.8/ruby-1.8.5-p2.tar.gz
tar xvzf ruby-1.8.5-p2.tar.gz
cd ruby-1.8.5-p2
./configure
 make
make install
cd ..

Note: If you receive error messages at the ./configure step, it’s probably because Developer Tools aren’t installed.

3. Download and install the latest version of Ruby Gems

You’ll need RubyGems in order to install Rails and some other required pieces of software, so we’ll do that now.

The current version as the time of writing is 0.9.1. You should already back in the /usr/local/src directory before continuing.

wget http://rubyforge.org/frs/download.php/16452/rubygems-0.9.1.tgz
tar xvzf rubygems-0.9.1.tgz
cd rubygems-0.9.1
ruby setup.rb

4. Install the latest version of Ruby on Rails

The gem command will automatically download the latest stable version of Rails, which is 1.2 at the time of writing.

gem install rails --include-dependencies

5. Install the required gems and dependencies

Next, install other required Gem libraries. The first line assumes you’ll be using MySQL as your database server.

gem install mysql -- --with-mysql-include=/usr/include/mysql --with-mysql-lib=/usr/lib/mysql 
gem install rake --include-dependencies
gem install capistrano --include-dependencies
gem install termios --include-dependencies

6. Download and Install FastCGI

Plesk already has mod_fcgid installed and enabled with Apache if you checked the mod_fcgid support option in your domain setup. You’ll still need FastCGI installed in order for things to work correctly, so we’ll do that now.

The current version of FastCGI as of writing is 2.4.0.

Make sure you’re in /usr/local/src/ before continuing.

wget http://fastcgi.com/dist/fcgi-2.4.0.tar.gz
tar xvzf fcgi-2.4.0.tar.gz
cd fcgi-2.4.0
./configure && make && make install

7. Install the FCGI gem

With FastCGI installed, you’ll need to install the FCGI RubyGem that will allow Ruby on Rails to use it.

gem install fcgi

8. Enable the vhost.conf file for the domain:

There will already be a couple of Apache configuration files created on your server, the master one located at /etc/httpd/conf/httpd.conf, and the domain specific one at /var/www/vhosts/<domain>/conf/httpd.include. Do not modify either of these! Both of these can be overwritten by Plesk, so your configuration changes aren’t guaranteed to be safe.

Instead, you create a vhost.conf and/or a vhost_ssl.conf inside the same directory as httpd.include to contain your changes. You might as well do both at the same time, just in case you decide to use SSL at some point.

touch /var/www/vhosts/<domain>/conf/vhost.conf
touch /var/www/vhosts/<domain>/conf/vhost_ssl.conf

Creating these files is not enough. Now you need to tell Plesk about them so they’ll be automatically included in your domain’s httpd.include file:

/usr/local/psa/admin/sbin/websrvmng -u --vhost-name=<domain>

9. Prepare for Deployment with Capistrano

At this point, I’m assuming your application is tested and ready to go on your local development machine. It should also be “capistranized” and your deploy.rb modified to suit your situation.

I suggest creating an app directory to hold your Rails application and telling Capistrano to use the domain’s username to do the deploy. You could do it as root, but you’re far less likely to run into permission problems of you use a regular user instead.

set :deploy_to, "/var/www/vhosts/<domain>/app/#{application}" # defaults to "/u/apps/#{application}"
set :user, "<username>"

On your development machine, run the following to setup the correct directory structure for your Rails app on your dedicated server:

cap setup

If Capistrano was able to do its job, you should now see some subdirectories with app on your server.

10. Edit the vhost.conf file to point to the public directory of the rails application

My first choice was to use a Symbolic Link to point httpdocs to the public directory within my Rails application, but I kept getting 403 Forbidden errors that I couldn’t work around. Instead, you can use the vhost.conf file you just created to tell Apache to use the Rails public directory as the web root instead.

In this case, current is the symlink created by Capistrano that points to the latest version of your deployed application.

  DocumentRoot /var/www/vhosts/<domain>/app/<appname>/current/public

  <Directory /var/www/vhosts/<domain>/app/<appname>/current/public>
  AllowOverride All
  Options +FollowSymLinks
  Options -Includes -ExecCGI
    <IfModule mod_fcgid.c>
      AddHandler fcgid-script .fcgi
      Options +FollowSymLinks +ExecCGI
    </IfModule>
  </Directory>

Restart the Apache webserver by issuing the command httpd -k graceful. This will make your configuration changes take effect.

11. Edit the htaccess file in the rails application /public directory

Before deploying your application to your dedicated server, on your development machine edit the .htaccess file located in the public directory of your Rails app:

# (around about line 2 change 
  AddHandler fastcgi-script .fcgi 
to ...
  AddHandler fcgid-script .fcgi
# (around about line 32) change 
  RewriteRule ^(.*)$ dispatch.cgi [QSA,L]
to ... 
  RewriteRule ^(.*)$ dispatch.fcgi [QSA,L]

This will tell Apache to use the built-in fcgid module (line 2) and tell the Rails app to use FastCGI instead of the much slower regular CGI.

12. Deploy Your Rails App

On your development machine, issue the following command when you’re at the main directory of your Rails app:

cap deploy

This will tell Capistrano to get the latest version of your application from your source management system, create a new directory for it, point current to its public directory, then restart the FastCGI processes.

You should now be setup to relibly deploy new versions of your application to your Media Temple Dedicated Virtual Server. That wasn’t so hard now, was it?