Yeah, we know. If you're just getting started with Rails, and you've been reading all these great articles by all these experienced Rails developers, it's pretty much inevitable. One day, you're going to see this:

You ARE using Capistrano, aren't you?

And you will say, well, no I'm not. I must be a complete idiot.

I admit it. The title of this post is only there to get your attention. No, you're not really a moron. In fact, there are plenty of experienced Rails developers out there not using Capistrano. But the fact is, if you're doing any kind of serious Rails application development, and you're in charge of deploying it (which you probably are), then yes, you should be.

When we .NET developers say that getting into Rails is tough, this is the kind of stuff we're talking about. Learning some basic Ruby in order to develop your first Ruby on Rails application is relatively straightforward for an experienced programmer. It's the Linux shell, server applications, and other things we're not used to that trip us up.

Before we continue, I have to tell you that this guide is for total noobs. There are plenty of great resources to help those experienced with *nix web servers and related technologies get started with Capistrano, including the official manual and the fantastic Capistrano Peepcode screencast (disclosure, a sponsor). However, if you have read this and acknowledge that, indeed, you are a total noob, let's continue.

Theory

The idea behind Capistrano is pretty simple:

• You haven't been spending all of your time developing that next great Web 2.0 application in Rails for nothing. You're ready to push said application out to the ol' "series of tubes".

So, if you didn't have Capistrano, you might do one of the following to get your code to its production environment:

• FTP your whole Rails app over.
• Use subversion to version control your app, then when you're ready, shell out via SSH to your production server (using PuTTY, perhaps), and get the code by checking-out/exporting from your repository.

Needless to say, both approaches are *so* not cool anymore. Not to mention that, in addition to getting your code where it needs to go, other things might need to get done - like restarting your web server, making some changes to your database, or cleaning stuff up. That said, all Capistrano basically does is automate the SSH-subversion-checkout method and lets you add whatever else you might need from there.

One important thing of note: Capistrano is a utility that runs on your workstation, not on the server. Therefore, there is nothing special that you have to do on the server-side to make it work. I'm surprised by the number of people I meet who misunderstand this, hence the yelling. The whole idea of Capistrano is to automate the most common tasks you might shell into your server to perform, to make sure you hardly ever have to shell into your server again. (In case you were wondering, it uses the Ruby Net-SSH library to do all the talking, so you don't need any particular SSH client installed either.)

Installation

Capistrano is distributed as a RubyGem, and as such, that's the easiest way to install it.

gem install capistrano --include-dependencies

After the Capistrano gem is installed, you use the newly available cap command to add a deploy.rb file to your Rails application's config directory. A lot of the guides out there will refer to this as "applying" Capistrano or "Capistranizing" your application... all you're doing is copying the one file to the config directory. Head over to the root directory of your Rails application, and type:

cap --apply-to .

The deploy.rb file (the "recipe")

The deploy.rb that gets created for you is a file that's often called the deployment "recipe". That's because, in many ways, it is indeed a "recipe" that describes how to assemble all the pieces that you need to run your application in production. Capistrano then takes your recipe and makes it all happen in one fell swoop.

The example code that's written to the deploy.rb includes a bunch of stuff by default, most of which you probably don't need for a basic deployment scenario. That said, it's a good idea to go through it and see what some of the options are. For the purposes of this exercise, here's our (very) minimal deployment recipe:

set :application, "softiesonrails"
set :repository, "http://somesvnrepository/trunk"
role :web, "mygreatrailsapp.com"
role :app, "mygreatrailsapp.com"
role :db, "mygreatrailsapp.com"

What's this recipe going to do when we run it? (We'll talk about how to actually run it in a moment.) Let's dissect it a bit.

• By specifying role :web "mygreatrailsapp.com", you're telling Capistrano that "mygreatrailsapp.com" is the server to which you'd like to deploy your application. You can obviously set different values for the various machines you may have set up in a more advanced situation; we're just using the same server for all roles (web, app, and database) here.
• By default, Capistrano will create a folder at /u/apps/ and stick your application code in there. So, in this case, a folder called /u/apps/softiesonrails will be created, since we've specfied "softiesonrails" as the name of our application. Then, a subdirectory, current, is where the latest version of your application lives. On a shared host (say, Dreamhost) you would have to override this setting and provide the full path to somewhere underneath your home directory. For example:

set :deploy_to, "/home/your_username/apps/softiesonrails"

• Capistrano works by SSH'ing out to your server and running some commands. In this case, here's what will happen once an SSH connection to "mygreatrailsapp.com" is established:
  • Take any code that's already in /u/apps/softiesonrails/current and archive it (a new directory that's unique by date and time will be created and the code moved there).
  • Check-out the latest source code from your subversion repository to the currentdirectory.

Time to deploy

Ok, your recipe is now set up, and you're ready to actually deploy your application. The very first time, you'll want to run:

cap setup

What this will do is SSH to your server, asking for a password first, and create the necessary directory structure and permissions for you. If you take a close look at the output of this command, you'll see the actual commands being executed. Don't worry if this fails the first time, just fix any errors that appear and give it another shot. Once the setup is complete, you can run your deployment recipe:

cap deploy

If you're really a total noob (and you probably are if you're still reading this), there's a good chance it will fail the first time. Not to worry, here are just a couple of troubleshooting tips:

• By default, Capistrano will try to use the same username on your subversion repository as you've specified for access to the server. You can easily override this by specifying the login credentials in the recipe:

set :svn_username, "brian"
set :svn_password, "secret"

• Your deployment may stall on asking for a subversion password. That's because, even if your subversion and server usernames match, the server is going to need to authenticate against your repository if it never has before. To do this (you only have to do this once), simply SSH to your server manually, go to a temporary directory, and check-out or export something (anything) from your repository. You'll be asked for credentials and be authenticated from that point forward.

What's Next

The basic recipe we've discussed here might just be enough for a lot of people to get started. What you do from here is highly dependent on your specific server setup (i.e. whether you're deploying on Apache, FastCGI, Mongrel, Litespeed, Nginx, a rack of hamsters, etc.) If you're hosting with one of the major hosting companies supporting Rails, you'll usually find some documentation on Capistrano on your hosting company's support area as well.

Bottom line: dive right in. You'll find it much less intimidating and daunting a task than it may seem at first. And, just like everything else with Rails, once you get comfortable with it, you'll wonder why you ever deployed your application any other way.

Image credit: Seattle Roll