1.4. Installing Rails

This section takes a break from discussing theory in order to get your environment set up. It provides you with step-by-step instructions for installing Ruby, Rails, and all the other necessary components of a development stack on Microsoft Windows, GNU/Linux, and Mac OS X.

For the Windows installation, two different methods are illustrated: the first leverages an installer and the second uses a learning environment known as Instant Rails.

1.4.1. Can You Use Rails on Windows?

Macs are very popular within the Rails community. If you ever get the chance to attend a Rails conference, you'll see a very high percentage of Apple laptops. The entire Rails core team uses Macs. The community seems to be keen on GNU/Linux as well, which is another common option for Rails development, and the most popular deployment one. In fact, most Rails hackers that I know develop on a Mac and deploy on GNU/Linux or *BSD, a combination that I adopt and enjoy myself.

You probably won't see many Windows systems. Generally speaking, the community prefers Unix-like environments and few people would admit in public to consciously choosing Windows at any Ruby or Rails venue. There are many reasons for this, most of which are cultural ones. Does this mean that you can't use Windows or that you'll be the only one doing it?

Although this book can be followed by utilizing any operating system of your choice, the assumption is that as a Microsoft developer, you're primarily familiar with Windows .NET, and other Microsoft developers often face a culture clash when trying to learn Rails. This book tries to minimize that by letting you take advantage of the tools and skills that you're already familiar with. For this reason, I've employed Windows to write this book, and the screenshots are from (the much debated) Vista.

Developing with Rails on Windows is usually not a problem, given that in the end we are just editing files, but it's a fair assessment to say that both Ruby and Rails work much better on Unix-like operating systems. For example, Ruby is significantly faster on Ubuntu, Fedora, or Mac OS X than it is on Windows XP (where it still performs better than it does on Vista).

Some people even go so far as to run Rails from within a virtual machine (using GNU/Linux or BSD) in Windows. There are also specific cases of libraries or particular deployment options that are well supported on, say, Linux, but not on Windows due to crashes and other problems. In general, it is recommended that you deploy your Rails applications on *nix systems, but it is understood that doing so is not always an option. You'll feel reassured to know that Rails can be deployed on Windows and that this is commonly done. Chapter 11 tells you how.

I wanted to give you a heads up about the special relationship between Ruby, Rails, their respective communities, and Windows, but please don't let this discourage you. Windows is a viable platform for Rails development and there are several initiatives to further improve the current situation. Rails' success and mainstream acceptance will also depend, in my opinion, on its ability to succeed on Windows, which is still the most popular operating system out there.

If you enjoy using Windows, I'll let you in on a surprising piece of information: Ruby is very popular on Windows. In fact, I'm going to prove its popularity in a somewhat scientific manner. Many Ruby and Rails projects are hosted at a site called RubyForge (http://rubyforge.org), the equivalent of SourceForge or CodePlex for Ruby. The most popular download is, surprise-surprise, a one-click installer for installing Ruby on Windows. As I write this, it has been downloaded about 3 million times. And the third most popular download is Instant Rails, a package that helps you to quickly get up and running with Rails on Windows (it's had more than 700,000 downloads so far). Rails on Windows might very well be a silent majority. In other words, and to quote Michael Jackson: you are not alone.

1.4.2. Installing on Windows

For this book you'll need to install the following components:

• Ruby: The Ruby interpreter plus its core and Standard Library. Ruby 1.8.6 or newer is required for modern versions of Rails (for example, 2.2.2 and newer).

• RubyGems: A packaging system used to install, update, and remove Ruby libraries and programs (packaged and distributed as "gems").

• Ruby on Rails: All the gems required to run Rails.

• Mongrel: A much faster server that we'll use in place of WEBrick.

• SQLite3: A lightweight, file based, ACID (Atomicity, Consistency, Isolation, Durability) compliant database that's available in the public domain.

• sqlite3-ruby: A gem used by Rails to access SQLite3 databases.

• Subversion: An open source version control system required to install many of Rails' plugins.

1.4.2.1. Installing the One-Click Ruby Installer

Windows is one of the easiest platforms on which to install such a complete Rails stack, thanks to the abovementioned One-Click Ruby Installer, which takes care of the first two elements in the preceding list.

To install it, follow these simple steps:

At this point Ruby, RubyGems, and a handy text editor called SciTE are all installed in c: uby (unless you specified a different location during the installation process).

To verify that the installation was successful, you can run a quick sanity check by opening the command prompt (cmd.exe) and running the following command:

ruby -v

Ruby should reply, stating its version number to the prompt; for example, on my machine I obtain the following: ruby 1.8.6 (2007-09-24 patchlevel 111) [i386-mswin32]. Ensure that you have Ruby 1.8.6 or newer, because this is a requirement for Rails.

1.4.2.2. Updating RubyGems

The version of RubyGems that ships with the One-Click installer may not be the most recent one. You can verify the installed version number by running gem -v from the command line and upgrade to the latest version by issuing the following:

gem update --system

This will fetch and install the latest version of RubyGems from the RubyForge repository, so you'll need to be connected to the Internet. When the update is finished, you should get the message "RubyGems system software updated" or similar, as shown in Figure 1-2.

Running gem -v again will give you the peace of mind that the update was indeed successful and that the command is still working.

Now that you've updated the system, you can proceed to update the actual gems that came with the One-Click installer by running gem update from the command line. You can obtain a list of installed gems by running the following command:

C:> gem list
*** LOCAL GEMS ***

fxri (0.3.7, 0.3.6)
fxruby (1.6.18, 1.6.12)
hpricot (0.6.164, 0.6)
log4r (1.0.5)
ptools (1.1.6)
rake (0.8.3, 0.7.3)
rubygems-update (1.3.1)
sources (0.0.1)
test-unit (2.0.2)
win32-api (1.3.0, 1.0.4)
win32-clipboard (0.4.4, 0.4.3)
win32-dir (0.3.2)
win32-eventlog (0.5.0, 0.4.6)
win32-file (0.6.0, 0.5.4)
win32-file-stat (1.3.2, 1.2.7)
win32-process (0.6.0, 0.5.3)
win32-sapi (0.1.4)
win32-sound (0.4.1)
windows-api (0.2.4, 0.2.0)
windows-pr (0.9.8, 0.7.2)

As you can see in the preceding output, when multiple versions of a gem exist, they are listed as well between parentheses.

1.4.2.3. Installing Rails

Now that the must-have RubyGems packaging system is installed, you can you use it to install a fresh copy of Rails by issuing the following command:

gem install rails -v 2.2.2

RubyGems Improvements RubyGems has come a long way. In its previous versions, the developer had to indicate the gem version and platform required during the installation of a gem. If you want to install a specific version of a gem, you can now use the --version or -v option (for example, -v 2.2.2). The dependencies weren't installed by default either, and the -y or --include-dependencies option was required to include them. Now that gem automatically installs the dependencies, you can specify the --ignore-dependencies option in the rare occurrence when you don't want them to be installed.

This command will fetch the rails gem version 2.2.2 and all its dependencies from the default source repository at http://gems.rubyforge.org (you can run gem source -l to see a list of sources used by the command). If you omit -v 2.2.2, the command will install the latest available version. This book uses version 2.2.2 so it's recommended that you follow along with the same version even if version 2.3 will be out by the time you read this.

No huge differences exist between Rails 2.2.2 and 2.3. At the time of writing 2.3's release date has not been announced but I will point out throughout the book when the known differences exist.

The installation process may take a while, as gem proceeds with installing Rails and five other gems plus their documentation, as shown in Figure 1-3.

To see a list of remote gems you can use the --remote option. When used in conjunction with list it can help you find gems by their name. For example, gem list sql --remote will show you a list of gems that start with sql (it's not case sensitive).

Gem places the rails command within c: ubyin, which is in the Windows's Path environment variable and therefore executable from any command prompt.

Running rails --version (or its shorter version -v) tells you which version is currently active.

1.4.2.4. Installing Mongrel

It's nice that Rails ships with an HTTP server. Unfortunately, even strictly for development purposes, it's not very fast. Through RubyGems you can easily install a much faster replacement called Mongrel that, in more elaborate configurations, is often used to run some of the largest Rails websites out there.

To install Mongrel, simply run:

C:> gem install mongrel
Successfully installed gem_plugin-0.2.3
Successfully installed cgi_multipart_eof_fix-2.5.0
Successfully installed mongrel-1.1.5-x86-mswin32-60
3 gems installed
Installing ri documentation for gem_plugin-0.2.3...
Installing ri documentation for cgi_multipart_eof_fix-2.5.0...
Installing ri documentation for mongrel-1.1.5-x86-mswin32-60...
Installing RDoc documentation for gem_plugin-0.2.3...
Installing RDoc documentation for cgi_multipart_eof_fix-2.5.0...
Installing RDoc documentation for mongrel-1.1.5-x86-mswin32-60...

This command installs the Windows version of Mongrel and the required dependencies as well.

A second gem, mongrel_service, exists for installing Mongrel as a Windows service. This is not needed for development but it's very useful when deploying an application, to ensure that Mongrel automatically starts if the machine reboots. You shouldn't worry about this gem until you are ready to deploy your application. This subject is discussed in Chapter 11.

1.4.2.5. Installing SQLite3 and sqlite3-ruby

SQLite version 3 is a very nice, lightweight, file-based (like Microsoft Access) relational database. It's ideal for quick prototyping (in development mode) even though you'll probably want to use a data server when dealing with all but the smallest amount of traffic in a production setting.

MySQL used to be the default database system for Rails, but now SQLite has taken its place, lowering the entry barrier for developing in Rails even further and quickly allowing you to get started. There are no users, authentication, or ports to configure: just simple files. In this book, I decided to stick with the default database. Switching to a different database system is most often trivial.

Installing SQLite is a piece of cake. Just download the DLL contained in a zip file that's available from the official website at http://www.sqlite.org/download.html. The current version at the time of writing is 3.6.10, so I downloaded the file sqlitedll-3_6_10.zip containing sqlite3.dll.You should grab the most recent version available.

Extract the zip file and place the DLL in a location on your path. c: ubyin is a good place, given that you're installing SQLite specifically for Rails development purposes.

You should also download the command-line program for accessing and modifying SQLite databases. It's available on the same download page, and its file name (as of this writing) is sqlite-3_6_10.zip. Again, extract it and place the sqlite3.exe file in c: ubyin. From now on, running sqlite3 from the command line opens the SQLite3 shell. Beginning with Rails 2.1, this shell can also be invoked using a Rails script (dbconsole), as explained in Chapter 5.

At this point you'll need to install the Ruby bindings through RubyGems as follows:

C:> gem install sqlite3-ruby -v 1.2.3
Successfully installed sqlite3-ruby-1.2.3-x86-mswin32
1 gem installed
Installing ri documentation for sqlite3-ruby-1.2.3-x86-mswin32...
Installing RDoc documentation for sqlite3-ruby-1.2.3-x86-mswin32...

The preceding command specifies version 1.2.3 because it ships with the Ruby bindings in binary form. The latest release, 1.2.4, attempts to build the Ruby extension from source, which is more complicated on Windows because it requires Ruby's development headers and nmake, Microsoft's version of make.

1.4.2.6. Installing Subversion

Subversion (SVN) is a very popular open source version control system. Though it might not be very accurate from a technical viewpoint, it may help you to think about SVN as an efficient and whittled down version of Visual SourceSafe or Microsoft Team Foundation Server.

SVN and similar alternatives are crucial for working on real projects, but in this context I invite you to install the SVN client tools, because they're required for installing Rails plugins. When you attempt to install a plugin, Rails essentially performs a checkout from the given remote Subversion repository you specified.

On Windows, you can get SVN from the URL http://subversion.tigris.org/servlets/ProjectDocumentList?folderID=91. The most recent setup file in the download list will do (in my case, that's svn-1.4.6-setup.exe). All that's left to do is for you to double-click the downloaded installer and go through the default setup process.

Setup takes care of concatenating the SVN bin directory (for example, c:Program FilesSubversionin) to your Path environment variable. Opening a new command prompt should now allow you to run svn and obtain in return a Type 'svn help' for usage message. It doesn't do anything too useful, but it's a good sanity check that guarantees you that svn.exe is available from the command prompt.

Many plugins are released on GitHub.com, a site that hosts thousands of projects that use the Git distributed revision control system. For this reason, you may want to install a Git client as well. On Windows, you could install msysGit (http://code.google.com/p/msysgit/). If you are new to Git, you should also check out "An Illustrated Guide to Git on Windows" available at http://nathanj.github.com/gitguide/tour.html.

1.4.3. Configuring Instant Rails

The original author of the One-Click installer (Curt Hibbs) created an alternative project called Instant Rails. Unlike the One-Click installer above, Instant Rails doesn't require any installation, nor does it modify your environment. You download a zip file, extract it to the folder of your choice, and you will automatically have a full Rails stack at your fingertips. The current version includes Ruby, RubyGems, Rake, Rails, Mongrel, support for SQLite3, MySQL, Apache, and PHP (for phpMyAdmin, which is used to manage MySQL), and a couple of sample Rails projects.

It essentially contains anything that'll you need to get started with Rails. You will need to manually install SVN, but other than that, you'll be all set (which helps explain the popularity of this package). Because it's such a great all-in-one package, it is very commonly used by Rails beginners who are working with Windows.

You could use Instant Rails while reading this book, but I don't recommend that you do so. Instant Rails is meant to be a development-only package, and it's not typically used in production environments. You're also somewhat tied to its management application (InstantRails Manager), even though you could manually configure the binaries to be accessible throughout the whole system. For as great as it is, Instant Rails remains a prepackaged solution that is not as flexible and "solid" as the manual installation previously discussed. On top of that, it could be using different version numbers and make this book harder to follow.

With that in mind, there are still times when you can't install software on your Windows system or, for whatever reason, prefer not to touch the existing environment. In such situations, Instant Rails is the right solution and you should have no qualms about giving it a spin. To install Instant Rails, follow these steps:

As per the "manual" installation through the One-Click installer, it is a good idea to update the installed gems, by issuing a gem update. In this case though, gem is not accessible from any command prompt, so you'll have to open the Ruby console from Instant Rails, by clicking Rails Applications Open Ruby Console Window.

You can also create and manage your applications by selecting Rails Applications Manage Rails Applications. The Rails Applications window will appear. To create a new application, you'd click the Create New Rails App button. What this does is simply open a command prompt, which is aptly located in (depending on the folder you picked in the beginning) c:InstantRails ails_apps.

These brief instructions should get you started on the right foot if you were not able to proceed with the recommended method in the previous section. Please note, however, that throughout the rest of the book, you won't find instructions that are specific to Instant Rails.

1.4.4. Installation on Other Platforms

This section is just a quick pointer in case you decide to get started with Rails on *nix systems rather than Windows.

1.4.4.1. Mac OS X

Apple has been shipping Ruby on its OS for some time now. The default Ruby installation on systems older than Mac OS X 10.4.6 doesn't work well with Rails. If this scenario applies to your system, you have a few options besides upgrading your OS.

You can download (http://www.ruby-lang.org/en/downloads/) and then compile and build from source code, if you are familiar with the process. If you're brave, this guide leads you through the installation step-by-step:

http://hivelogic.com/articles/2005/12/ruby_rails_lighttpd_mysql_tiger

You can also simply use one of the popular distribution systems like MacPorts (http://www.macports.org) or Fink (http://www.finkproject.org). You should install the whole stack that I pointed out in the Windows section in order to successfully follow this book and start working with Rails projects.

The two preceding methods are only needed if you are running a Mac OS X version that's older than 10.4.6. But it's not uncommon for developers to install their own customized stack rather than to rely on Apple's copy.

A much easier alternative for beginners is Locomotive (http://locomotive.raaum.org), a popular project with similar aims (and arguably caveats) to those of Instant Rails, but targeted for Mac OS X.

If you are running Tiger, with a version number equal or greater than 10.4.6, your Ruby installation is good and you'll just need to update RubyGems, the pre-installed gems, and then proceed with the installation of Rails. Conversely, on Leopard (Mac OS X 10.5.x), Rails, Mongrel, and a series of other goodies are already included for you and you'll just need to update them to the latest version. In both cases, you can run the following commands from the Terminal:

sudo gem update --system
sudo gem install rails
sudo gem install mongrel
sudo gem update

1.4.4.2. GNU/Linux

If you are using GNU/Linux, you're aware of the many variants (aka distributions, or distros for short) available. It would be impossible for me to provide instructions on how to proceed for each of them. Chances are that no matter what package management system your GNU/Linux version adopts, Ruby 1.8.6 or later, RubyGems, SQLite3, and SVN will be around for you to work with. From RubyGems you can do the rest by updating RubyGems itself, installing (or updating) Rails and Mongrel (and optionally sqlite3-ruby if not available through the package management of your distro).

One of the most common distributions nowadays is Ubuntu (and its variants like Kubuntu and Xubuntu). As an example, I've provided the following instructions on how to set up a Rails stack on version 8.04 of K/X/Ubuntu:

sudo apt-get update
sudo apt-get install build-essential
sudo apt-get install subversion
sudo apt-get install ruby-full rubygems libsqlite3-dev libsqlite3-ruby1.8

sudo gem update  --system
sudo gem install rails
sudo gem install mongrel
sudo gem update

You'll also have to add Gem's bin folder to your PATH, by adding the following line (or a similar one, if you're not using the default BASH shell) in your shell profile (for example, in ~/.bashrc):

export PATH=$PATH:/var/lib/gems/1.8/bin

By the time you read this book, things may have changed, but several people have reported a few issues with the RubyGems version installed through apt-get. Alternatively, you could remove rubygems from the preceding instructions and install it manually by downloading and building its source code (http://rubyforge.org/frs/?group_id=126) before proceeding with the last four instructions.

1.4.5. RubyStack

BitNami produces several open source multi-platform installers for popular development stacks. Among these, RubyStack installs Ruby, RubyGems, Rails, ImageMagick, Subversion, SQLite3, MySQL, Apache, PHP, and phpMyAdmin. Their installer works with Windows, GNU/Linux, and Mac OS X and, unlike Instant Rails, performs an actual installation and provides scripts to manage the various servers installed.

If you're struggling with alternative installation methods, you may want to give RubyStack, available at http://bitnami.org/stack/rubystack, a try.