First Five Capistrano “Oh Crap! Oh No!” Tips

In a slight segue from our agile project articles, here are five tips that may help other first time Ruby on Rails / Capistrano deployments. Even with the great resources available on the internet, there were some unexpected and obscure hurdles for a new-to-rails developer to get a site up and running. While Ruby favors convention over configuration, not all hosts are set up with the same conventions – so there isn’t much help available for the really weird problems.

First, let me say that I heart Capistrano. And after less than two weeks using Ruby and Ruby on Rails, I am very excited. That “two weeks” bit is important – experienced people don’t tend to run into the problems that I did – or they at least don’t tend to write about them enough.

Capistrano (Cap) is a tool for deploying software to (one or more) servers while they are running, that allows you to do the updates with minimal overhead – it synchronizes steps, restarts servers, and automates “everything.” An agile development project will deploy software very frequently – so completely automating that process is a great thing. Cap can deploy software that isn’t Ruby on Rails, and it can use a source code control system that isn’t subversion. If you’re doing that stuff, this article probably isn’t for you, but Cap probably still is.

There are several good tutorials and explanations of what to do, in what sequence. And the process is actually very simple. The challenge comes from tutorials that say “type X, then type Y.” Well, what if “X” throws an error? Then what? Occasionally an article would explain why I needed to type X. But most articles glossed over those details. Perhaps X normally doesn’t fail.

But the devil is in the details, and trying to find the exorcism rituals with Google was tedious and occasionally fruitless.
The “solutions” presented below may not give you complete answers. Think of them as clues to help you Google for more expert advice. Like a software development scavenger hunt.

That said, here are the first five “Oh Crap!” and “Oh No!” challenges I faced while attempting to deploy my first prototype with Capistrano.

First Five Capistrano Tips

1. Imitation is More Than a Form of Flattery

Site5 is my web-host, and they host Ruby on Rails sites, as well as subversion repositories. Last week I installed Ruby on Rails and subversion, and created an application prototype. Over the weekend, I attempted to deploy it, and failed. One likely source of problems – Site5 was running different versions of Ruby and Rails than I was. Running different versions of Rails is fine – because you can “freeze” your version of rails within your application. Running a different version of Ruby was possibly not so smart. Note – this tip is for deploying into a shared server environment. If you control the server, you still want to match versions, but you have the choice to change either end.

Earlier this week I rebuilt my environment to use the same version of Ruby as my host.

2. Shebang Nabit!

Most Ruby on Rails developers apparently use a version of Unix for their development environments. Apple OS-X and Linux are both versions of Unix. I am using Windows XP. My Site5 server is running Linux. Every third article warned me to not try and deploy to a server running Windows, so, “whew!”

At the top of a few important files in your code is a “shebang” line – #! c:\dev\ruby\bin in my case. This line tells the operating system where to find the Ruby executable. This allows you to issue commands without typing “ruby” first.

The location of the Ruby files on your dev machine is irrelevant. You need to change this so that the server can find Ruby without your help. That probably means changing the line to #! /usr/bin/ruby. You can find out exactly what you have to change it to by typing whereis ruby into a command prompt on the server. I used putty to create a bash shell command prompt. You may have to request access to get this (I did) – but this part is covered in many tutorials.

3. Is The Computer Plugged In?

In the early days of tech support, many a laugh was had among the IT people when resolving a user’s problem amounted to turning on the computer, or telling them not to stick floppy disks to the side of the desk with a magnet. Ah, the golden years.

I got myself into a bad spot, trying to roll-back my software versions to match my host. Suddenly, my dev environment didn’t work any more either. The error messages didn’t help me to google the solution, so my problem must have been way out in the long tail of stupid mistakes. My theory? I must have misused subversion, and created a mixture of old and new files.

The reality? My dev environment was not working because my local mySQL and Apache servers were not running. When I turned them on, it worked. Pebkac (problem exists between keyboard and chair). So, make sure they are running in the future. Also – I received a helpful suggestion that WEBrick (the Ruby-based development-environment web server that is installed by default with Ruby) will occasionally throw inexplicable errors. Well, I’m sure the errors make sense, but as a n00b (that’s l33t (elite) speak for plebe), they would certainly be inexplicable to me. Forewarned is forearmed.

4. Ask for Permission, Not Foregiveness

Later on, Capistrano was doing everything great, apparently. I checked code into subversion, typed cap deploy on my dev machine, and magically, the latest version of my code was now on my server, ready to run. Except it wouldn’t run.

File permissions is something that winxp mostly takes care of for you – you never have to think about it. To most users, “permissions” invokes images of someone password protecting an excel spreadsheet and emailing it to you. Well, permissions matter a lot on a server. They define who can do what with which file or directory. Who is an interesting concept to a server. I have a user account that I use to install my appication. Capistrano installs files for me, as me. But Apache (the web server) may not be running as me, since this is a shared server.

There’s a file called dispatch.fcgi that Cap has deployed for me, that Apache needs to interact with. chmod 755 dispatch.fcgi takes care of that problem.

5. Equivalence is NOT Equality

With the help of some awesome guys at AustinOnRails.org, we took a very instructive debugging approach – manually doing on the server, one step at a time, what Capistrano was going to do for me later. Eliminating variables and issues step by step.

One thing Capistrano does is get the latest source code out of subversion and put it where it belongs on the server. OK, easy to do. svn co file:///.... is the command to get the latest version of source from a subversion repository on the same machine. I was typing the command through my bash shell (running on the server), so that made sense. And it worked. Once we had everything running, we were ready to let Cap do its magic and automate the steps we confirmed manually.

Well, Capistrano runs from your local dev machine. And it uses the command svn co svn+ssh://... to push data from subversion to the server. And it appears to work. But it didn’t actually work.

It turns out that getting the same source, from the same repository, and putting it in the same place, is equivalent but not equal. Subversion is smart. And when we used the “file” accessor to create a working copy of the source the first time, it knew that the “svn+ssh” (tunnelling) accessor for the same stuff, to go in the same place, is actually not the same. So we didn’t get any updates.

Most people probably never have to do the manual steps that I did. So they don’t run into this problem. The solution – delete everything. Scary. Only delete the files and directories that Capistrano created. And don’t blame me when you delete something you shouldn’t. But delete is what I did. Your mileage may vary. Then run cap setup, and if that works, cap deploy. And it will pull down the latest code from subversion. Then change something, check it in, and run cap deploy again. It will get the changes.

Conclusion

Seriously. Love this stuff. Wish it had been as easy to deploy the app (as a new-to-deployment developer) as it was to create the app (as a new-to-ruby developer). I hope google finds this, and puts it somewhere where it helped you. Let me know if it did.And experts – please correct any boneheaded things I said above, or provide some links to great tutorials to help people on their scavenger hunts.