Update: Instructions have been updated for Capistrano 2.0. More info can be found here and here.

Capistrano is a small RubyGem that is designed to run a number of scripts on a remote server and is used primarily to deploy applications. Think of it as an automated way to grab the latest revision of your application from Subversion, upload it to your domain and then restart the server to take into account the changes.

Assumptions

First of all, I’m assuming that you’ve already been able to setup your Ruby on Rails application on TextDrive. In other words, you’ve already configured and ran Lighttpd as well as Ruby. We will need to edit those configuration files, primarily those located in your /etc/lighttpd directory later on. If not, follow these directions.

I’m also assuming that your app is installed on a secondary domain (not primary domain of shared account) and is located in the following directory: /users/home/USER/domains/DOMAIN.tld/web. You can easily adjust the following walkthrough for a primary domain setup by adjusting the paths.

On top of it all, you must already have Subversion repository setup on your server and have committed at least one time to it. I realize this is also a pretty complex thing to setup, especially for someone new, so expect a post in the near future on it. For now, use the following directions.

Installing Capistrano

On your local machine, open up Terminal (I’m on a Mac) and install Capistrano by executing the following line:

gem install capistrano

This is the easy part and you should now be able to use the cap command in console.

Still with me so far? At this point, you’ve installed Capistrano and should now be ready to set it up.

Deployment Recipe

Capistrano uses a file called ‘Recipe’ to deploy your application. It provides it with directions to your server, Subversion repository and your main account username. Main account has access to all the repositories, so it’s easier to use.

Rails creates a default recipe for you in a file called deploy.rb in the /config directory. Open it up in your favorite editor and replace everything with the following recipe:

set :user, "" # Your main account username
set :domain, "" # Your secondary domain name. For ex: myname.com
set :txd_server, "" # The TextDrive server you're currently located on. For ex: nicola.textdrive.com
set :subversion_repo_name, "" # Your Subversion repo name. For ex: repos
set :application, "" # The name of your application (ie. youtilize)

set :repository, "svn+ssh://#{user}@#{txd_server}/users/home/#{user}/domains/#{domain}/svn/#{subversion_repo_name}/trunk" # Edit this path if you're installing on primary domain or your SVN repo is located elsewhere
set :deploy_to, "/users/home/#{user}/domains/#{domain}/web" # This is where files will be uploaded to

role :app, "#{user}@#{txd_server}" 
role :web, "#{user}@#{txd_server}" 
role :db, "#{user}@#{txd_server}" 

namespace :deploy do
  desc "Restart Lighttpd and Ruby" 
  task :restart, :roles => :app do
    run "pkill lighttpd; pkill ruby" # Kill processes
    run "nohup /users/home/#{user}/etc/rc.d/lighttpd.sh start; nohup /users/home/#{user}/etc/rc.d/rails.sh" # Start processes
  end
end

Go ahead and follow directions in the file to fill in the blanks with all your information.

Capistrano 2.0 doesn’t automatically use the Rail’s recipe we just setup, so run the following to put finishing touches on the recipe setup:

capify .

At this point you’ve given Capistrano a recipe to follow when deploying your application.

Setting up your directories

Capistrano now needs to install default directories and chmod them accordingly to them give proper permissions. Aren’t you happy you don’t have to deal with permissions?

To do this, delete everything in your /web directory of your secondary domain.

cd /users/home/USER/domains/DOMAIN.tld/web/
rm -rf .

It’ll give you an error about not being able to delete .textdrive file. That’s fine, leave it be.

What you’ve done now is effectively wiped out your whole application! Don’t worry, in a couple of minutes, Capistrano will put it back for you. It first needs to install a couple of directories of its own, so execute the following:

cap deploy:setup

This installs two directories in your /web directory: /web/shared, and /web/releases. It also installs a system link in /web/current that will point to the latest release of your application. So, your actual application will now live in /web/current NOT /web where your server is currently pointing to. So we need to adjust that:

Reconfiguring your Lighttpd

Grab both lighttpd.conf from /users/home/USER/etc/lighttpd and your APPNAME.conf from /users/home/USER/etc/lighttpd/vhosts.d (Rememeber, APPNAME is whatever you named your .conf file before). You can do this step via FTP.

In ligghtpd.conf, change:

server.document-root = base + "/domains/DOMAIN.tld/web/public/"

to:

server.document-root = base + "/domains/DOMAIN.tld/web/current/public/"

Next, in APPNAME.conf, change:

server.document-root = base + "/domains/DOMAIN.tld/web/public/"

to:

server.document-root = base + "/domains/DOMAIN.tld/web/current/public/"

Don’t forget to change DOMAIN.tld to your domain name. Re-upload the files to their proper directories and guess what:

You’re all set to deploy!

Ready, Set, Deploy!

To deploy your application, on your local machine execute the following in you app directory:

cap deploy

You will be asked for your server password, so type that in (probably multiple times) and watch the process. At the end, Capistrano will restart the server for you and you should be able to load your site in the browser. In case the server doesn’t start, start it manually first time around.

Don’t forget to commit your recent changes to the Subversion repository before deploying:

svn commit -m="Bug fixes" 
cap deploy

Best of luck and hope this saved you many grueling hours.