Rails on Windows - Part 1 (Capistrano on Windows)

Published on Monday, 25 June 2007

As soon as you’ve spent some time dealing with Rails, you’re bound to hear the fact quoted that the entire Core Rails Team does their work on Macs. There are likely several reasons for this: (1) these folks really like Macs (you can’t fault them for that); (2) they’re getting kickbacks to use Powerbooks (could be; not likely though); or (3) Rails is fun, and using Windows puts a bit of damper on that fun. I think the last answer is the most likely even though I’d like to think that Steve Jobs has some skin in the Rails game.

Rails on Windows - Part 1

What you’ll also hear and experience when dealing with Rails is that it’s “opinionated software”, which it is. It just so turns out that the prevailing Rails opinions tend to align more closely with the UNIX-derivative camp (like Mac’s OS-X) than with the Windows camp. There’s a price to pay for working against the prevailing opinions and using a Windows environment to do your development. In most cases, the community that supports Rails has done a great job to make sure that this cost is very miniscule. However, once in a while, when you’re working with a Ruby Gem or Rails Plugin that is outside the core framework, you’ll hit the opinionated software wall head-on.

This is not meant to be a critique of Rails or the concept of opinionated software. Rather, the things that make Rails and some of these Gems and Plugins so special is that they leverage existing capabilities of the underlying operating system (that’s Rail’s DRY principle in action) such as the UNIX symlink command that powers Capistrano. These capabilities are difficult or impossible to replicate across operating systems; leaving the Windows-based developer with three choices: buy a Mac; install Linux, or hack your way through.

In the first of x installations of my experiences with Rails on Windows, I’ll touch on some of the learning points I had with Capistrano. As a refresher, or for the completely uninitiated, Capistrano is, in the simplest sense, a Rails deployment utility. It provides a collection of tasks that anyone with experience in deploying Web applications will immediately recognize as extremely useful. Tasks like automated deployments, checking the differences between your most recent source and the existing deployment, temporarily disabling an application and putting up a maintenance page, performing database migrations, and rolling back your application to previously deployed versions can each be performed using a single Capistrano command. Like many things Rails, the obvious utility of such functionality may lead you to wonder why a tool like this wasn’t invented much sooner and used universally.

Capistrano is quite overt about being opinionated software, going as far as to clearly document the assumptions it makes. Amongst these assumptions is that you are deploying to a POSIX-compliant UNIX shell (sorry, no Windows), you are using Subversion for source control, and that all your passwords (i.e. production server and Subversion) are synchronized. Once again, following the Rails convention, some things that Capistrano assumes are overridable. Other things, however, are not. Some of the learning points I touch on below are directly related to Windows; others are not.

  • You’re going to need the full Subversion binaries. If you, like me, had gotten by using various Subversion clients (e.g. TortiseSVN and Subclipse), the gig is up. You’re going to need Subversion anyway if you ever plan to run EdgeRails
  • Some installation instructions for Capistrano will specify that you should –include the termios Gem when installing Capistrano. Normally, termios removes the need to display and manually enter your password during the execution of Capistrano tasks. However, since the termios Ruby Gem is simply a wrapper around the POSIX termios command, this won’t fly with Windows. Solution: don’t include a termios dependency and get used to entering your password each time you invoke Capistrano from Windows.
  • If your Capistrano install fails with a Zlib::BufError, don’t fret it. Try updating your gems (gem update –-system). This seems to be a fairly common occurrence with Windows. I’ve heard of folks having to update gems multiple times for this to take.
  • Another must for Capistrano deployment, and one that escapes folks who have spent life in the Windows world, is the need to chmod files so that they have the appropriate permissions set. This is especially true for the Ruby and FCGI dispatch files (if you’re using FCGI). Ideally, you should create your Rails projects on the UNIX box you plan on deploying to, check it into Subversion, and then begin work on your Windows development machine from there. This helps to avoid a host of issues such as chmod problems and bad shebang lines that routinely plague Windows users.
  • Select a hosting provider that has one or more sample Capistrano deployment files available or that have customized the standard Shovel file for their environment. You’ll still have to do some tweaking but this will help save a good deal of time. Suffice it to say that if your hosting provider doesn’t know how Capistrano works, turn and run… fast.
  • If you maintain critical files outside of Subversion such as your database.yml or if you have multiple copies of the same file (e.g. different environment.rb files for staging and production deployments), the simple Ruby put command goes a long way. For example:
put(File.read('config/database.yml'),"#{deploy_to}/current/config/database.yml", :mode => 0444)
put(File.read('config/environment.staging.rb'),"#{deploy_to}/current/config/environment.rb", :mode => 0664)

There are plenty of purists out there that have invented all sorts of ways to get unversioned files onto your productions server if need be. I don’t see the need for such complexity, especially if only one or two people have been granted deployment rights with Capistrano.