Deploying to Dreamhost with Capistrano

I fantasize about the day when we’ll be running on a co-located server where I’ll have full control of configuration, software installation, etc., but for the time being, we have shared hosting. (Actually, I fantasize about the day when we’ll be running a rack of servers behind a load-balancer. I’m not sure if the co-located box of our own is “starting small” or a case of even my fantasies having fantasies.)

Also, new as it is, the Rails community has already embraced a number of conventional-wisdom processes handed on as best practices; one of them is using Capistrano to automate deployment from the trunk of our Subversion repository to the production server. Or, as one of the tutorials I read started,

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.

But it’s not really that simple. Maybe you’re not using Capistrano because getting it set up initially was a real pain.

When you first “Capistranize” a Rails app, you get a hefty deploy.rb file which is almost completely non-useful to you and your application. The basic tutorial suggests a basic file which is useful but still has problems on your actual deployment server. You go through the generated file, fixing configuration lines to match your installation (you think) and run cap deploy, and… long error messages.

Here are three distinct steps we took to solve some of the error messages and get Capistrano working.

• Remove the :db role: Capistrano attempts to make SSH connections to every host listed with a role in deploy.rb. If you’re with a shared host, odds are you don’t have shell access to your database machine. You’ll be prompted for a password, then get an error which looks like this:
  

  ** [update_code] exception while rolling back: Net::SSH::AuthenticationFailed, commonkitchen
authentication failed for `commonkitchen'


  Commenting out the :db role is sufficient to stop Capistrano from trying to connect to that host, and lets you move on to the next problem. Update: not having that role keeps migrations from being run. Instead, set the :db role to be the same hostname as the other roles.

• Use a “standard” repository layout: I say “standard” because you’re free to lay out your repository however you wish. However, we initially had all our app at the top level of our repository, and Capistrano was trying to find it in the trunk/ directory. Best to use the recommended layout described in the turtle book… or at least keep your application inside a trunk directory, even if you never use tags and branches. The errors are thick, but somewhere will be one that looks like this:
  

  /usr/local/lib/ruby/gems/1.8/gems/capistrano-1.4.1/lib/capistrano/scm/subversion.rb:24:in `latest_revision': Could not determine latest revision (RuntimeError)

  Ultimately, it’s easier to rearrange your repository than teach Capistrano to drop the trunk path.

• Let Capistrano create the web root: When we set up the virtual host on our server, the root directory (~/application/current/public) was automatically created by that setup. Capistrano would then create the rollback directories, but couldn’t create a symlink to the current directory. We got errors like this:
  

  command "~/application/current/script/process/reaper" failed on ourserver.example.com

  Once the current directory and its children were deleted, Capistrano was able to create its own current with a symlink to the most recent version, and everything was fine. (We figured this out from this tip.)

Now that Capistrano is working, it’s great to be able to deploy a revision with a single command. But getting there is less than simple, unfortunately.

Update: There’s a fourth tip I missed.

Update, 22 July 2007: Capistrano 2.0 is out now, so it’s worth noting that all the notes above were based on version 1.4.1. As of today, we haven’t upgraded yet (nor are we hosted on Dreamhost any longer) so use this information at your own risk.

This entry was posted on Saturday, June 16th, 2007 at 2:39 pm and is filed under Ruby on Rails. You can follow any responses to this entry through the RSS 2.0 feed. You can leave a response, or trackback from your own site.