This guide walks you through setup instructions for preparing a Windows Vista development machine to be used for general Ruby on Rails coding. This baseline setup is what we use for our LearningRails online course.

You will end up with a development machine with the following baseline components:

1. Ruby and all basic Ruby utilities
2. Ruby Gems package manager
3. Subversion client
4. MySQL database client utilities and server
5. Gems for Ruby on Rails, Capistrano, Mongrel, Mongrel Cluster, and MySQL
6. SSH Terminal Program
7. Git client (UPDATED)
8. Programmer’s editor or IDE

Note: In the command sequences we illustrate here, command line prompts are shown as C:\>.

Prerequisites

This guide assumes you have a Windows computer running the current Windows Vista operating system with up-to-date service patches applied (SP1 or higher). It also assumes you have not set up alternate Ruby on Rails tools prior to running through this guide. If you have, then small adjustments may be required as you walk through the following instructions.

You will need to have access to an Internet connection to complete various download steps.

You will need to have administrator access to your computer to complete this guide. Some of the Windows installers may ask you for your password. With most of the installer programs described below, Windows Vista will present the famous User Account Control (UAC) dialog asking whether an unidentified program should be permitted to have access to your computer.

You should select the “Allow” option which will let the specific installer program continue. In the specific case of MySQL, the MySQL installation process is not compatible with UAC. We will walk you through temporarily turning UAC off so you can install MySQL.

The Recipe

Follow this recipe in sequence. If you have previously installed a particular component, you can usually skip the associated step.

Ruby and Ruby Utilities (irb, ri, rdoc)

The One-Click Ruby Installer does a lot of work for you by installing Ruby, Ruby Gems Package Manager, Rake, all of the other standard Ruby tools, and even the open source SciTE programmer’s editor. Additionally, the installer configures the command line interface path information, so the Ruby tools are ready to use in the Command Prompt program.

Download the latest installer (1.8.6 r26 as of this writing) and double click on it to get started.

Select all of the default settings and let the installer complete its work. Once done, open a Command Prompt (aka DOS Command Line) window by selecting the Start menu, then enter cmd into the Start Search text box and pressing return.

You can check that Ruby is installed by typing the command:

    C:\> ruby -v
    ruby 1.8.6 (2007-09-24 patchlevel 111) [i386-mswin32]

You should seem similar responses. If you get an unrecognized command error, try closing your Command Prompt window and opening another one.

Ruby Gems Package Manager

You next need to install the latest version of gem.

Check the version that gets installed:

    C:\> gem -v
    0.9.4

You need 1.0.1 or newer. If you have an older version, you can update with the command line: gem update --system.

Installing a Subversion client

Subversion will be used to access your source code repository during development and deployments. You will need a current version of the Subversion command line client and you can use the official Windows installers on subversion.tigris.org.

Download the latest “Windows installer with the basic win32 binaries” option on the site. Double click the setup program and select the default options.

Once the installer is done, open a new Command Prompt window and check the installation:

    C:\> svn --version
    svn, version 1.4.6 (r28521)
       compiled Dec 20 2007, 16:33:06
    ...

Installing MySQL via the Offical MySQL Installer

You will be installing MySQL via the official Windows Essentials installer from MySQL.com. This installer handles all of the setup steps for you.

NOTE: As of this writing, MySQL 5.0.51a and 5.1.23rc have bugs that prevent simple installation onto Vista. A workaround recipe is available but it is complicated. We recommend using a slightly older version, MySQL 5.0.45, as it doesn’t have the current installation bugs. We’ll update these instructions once fixes to the current MySQL line are available.

Unfortunately, the MySQL installer and Windows Vista User Account Control (UAC) conflict with one-another. You will have to temporarily turn UAC off.

First, go to the Start Menu, select Control Panel, and then click on User Accounts and Family Safety:

Click on the User Accounts link to open your account’s setting dialog:

Click on the Turn User Account Control on or off link. Assuming that User Account Control is still on, Windows Vista will ask for permission to continue with turning User Account Control off. Nice and circular, yes? Now you can actually turn UAC off. Unselect the checkbox and press OK.

You will be prompted to restart your computer. Go ahead and do so now.

One other change you will need to make is to open your Windows Vista Firewall to permit MySQL connections to the MySQL server port (3306). To do so, open Control Panel again, and select the Allow a program through Windows Firewall option of the Security group.

Press the Add port... button, and enter MySQL in the “Name:” field and 3306 in the “Port number:” field. Leave the protocol as “TCP”.

Press OK on the Windows Firewall Settings dialog box and close the Control Panel.

Finally, you can get on with installing MySQL. Double-click the community edition (open source) Windows Essentials MySQL setup program to get started:

Select the default (“Typical”) settings and location and let the program install itself. After it completes, a few ads will be shown, then a final dialog allowing you to configure the MySQL server. Make sure the check-box is selected and press “Finish”.

The “MySQL Server Instance Configuration Wizard” will run next. Choose the “Detailed Configuration” option and select all of the default choices. Doing so will configure the database to be running with settings best designed for a developer’s computer. When you get to the dialog offering the “Include Bin Directory in Windows PATH” option, we suggest you select it. If you don’t choose this option, you will need to manually set up your path so the “Command Prompt” program has easy access to MySQL client programs.

You will also be presented with a dialog to set a root password. If you are going to be working locally and aren’t worried about security, you can deselect “Modify Security Settings” and have a blank root password. We strongly suggest you set a password to be safe.

You can confirm that MySQL is running by trying to fire it up in the Command Prompt program:

    C:\> mysql -p -u root
    Enter password: ****
    Welcome to the MySQL monitor.  Commands end with ; or \g.
    Your MySQL connection id is 1
    Server version: 5.0.45-community-nt MySQL Community Edition (GPL)

    Type 'help;' or '\h' for help. Type '\c' to clear the buffer.

    mysql> exit

When you reboot your computer, MySQL will start automatically in the future.

Once you have confirmed MySQL is working, you can also reverse the steps above for re-enabling User Account Control.

Gems

While the One-Click Ruby installer added some common Windows oriented gems for you, you still need the Ruby on Rails gems and the gems used in the LearningRails course. Install them with the command:

    C:\> gem install rails capistrano mongrel mongrel_cluster

All installed gems (including Ruby on Rails and its dependencies, Capistrano, Mongrel, and Mongrel_Cluster) will get installed at their latest versions.

The MySQL adapter gem needs to be installed next.

    C:\> gem install mysql

Once the command completes, you should be all set with the baseline gems you will need for the LearningRails courses.

SSH Terminal Program

In deployment environments where your production or other remote servers are running a Unix-derived operating system, you will want to log in to those machines using the SSH protocol. A good Windows SSH terminal program is PuTTY. Download the complete Windows installer and double click to let it run.

You can select all of the default options. Once the installer finishes, you are good to login to your remote machines.

Installing a Git client

Git is all the rage in the Rails world now and has pretty much replaced Subversion as the version control system of choice. That said, both are in common use. The Git on MSys project team has done a nice job of building the git tools and a simple installer for Windows.

Download the latest installer (latest as of the last update of this article was Git-1.5.6.1-preview20080701.exe) and double click the executable.

During setup, you will be presented with a number of screens. Select the defaults until you get to the following two dialogs:

1. “Adjust your PATH environment” dialog. Select the “Run Git from the Windows Command Prompt”.
2. “Choosing the SSH executable” dialog. Select “Use PLink” since we just installed Putty.

The installer should complete, and you can optionally review the ReleaseNotes.rtf file.

The installer command places the core git tools and the man page documentation (type git help _commandname_ for help) on your machine and updates the PATH so you can use git from the Command Prompt. ruby script\plugin install should find git and use it for installation of newer plugins.

Note that if you have an older Rails project, you’ll want to update to Rails 2.1 or newer to get the latest support for git. When you upgrade, update your project with the rake rails:update command.

Code Editing Tools

While you can get by with using a plain text editor like Notepad you will have much high productivity if you use a programming editor that is highly tuned to Ruby on Rails development. The One-Click Ruby installer automatically installed the SciTE programmer’s editor. SciTE is ok for basic tasks with one or two files, but we recommend trying some of the other programs below.

We use the commercial TextMate programmer’s editor for much of our day to day work on the Macintosh. TextMate is highly extensible through a collection of community supplied “bundles”. There is a Windows “look-a-like/port” called the E Text Editor that looks promising and includes much of the functionality found on the Mac. Even better, it is supposed to be compatible with TextMate bundles, so as functionality improves for one platform, it should become available on the other. Worth trying the trial at the least.

There are a variety of good open source or free programmer editors available too. On the open source side you can find ports of vim and emacs, both of which have add-ons to create a full featured Ruby and Rails development tool set. jEdit is a very extensible open source editor written in Java that has a decent Ruby programming plugin set.

Whatever editor you choose, be certain that it provides easy navigation among a large number of open files. Working with Rails applications generally involves dealing with a lot of small files, and that process needs to be efficient.

If you prefer an all-in-one tool, you should look at one of several integrated development environments that exist for Ruby. We use Netbeans in our LearningRails courses, but you should check out the numerous other options listed at BuildingWebApps.com.