I’ve written numerous guides over the years on installing Ruby on Rails on Snow Leopard. This is an amalgamation of that knowledge and experience. It’s also my last guide that I’ll write for Snow Leopard now that OS X Lion is on the horizon.

Let’s jump right in.

Installing XCode

This whole process breaks down if you don’t install XCode, so we’ll do that now. You can use the XCode that came with your install DVD or download it online.

Installing Homebrew

I used to use MacPorts as my package manager but I’ve recently switched over to using Homebrew. Installing Homebrew is easy since OS X comes with a version of Ruby pre-installed.

ruby -e "$(curl -fsSLk https://gist.github.com/raw/323731/install_homebrew.rb)"

Follow the instructions provided by Homebrew to complete the installation.

Installing Git

Pretty much every Rails hacker out there uses Git, so let’s grab that using Homebrew.

brew install git

Optional Install: wget and oh-my-zsh

The following is completely optional, but I recommend them. By default, OS X uses the bash shell when interacting with the terminal, but that’s not the only shell available. I prefer zsh myself and for my install process, I use Robby Russell’s oh-my-zsh. It’s easiest to install oh-my-zsh with wget, so we’ll install that first.

brew install wget

Once wget is installed, installing oh-my-zsh is easy.

wget https://github.com/robbyrussell/oh-my-zsh/raw/master/tools/install.sh -O - | sh

Follow any prompt by the install script to complete installation. Closing and re-opening your terminal should launch zsh from now on. To check run this command:

ps -p $$

You should see zsh instead of bash. If you don’t you can switch your shell manually by running the change shell command.

chsh -s /bin/zsh

Installing RVM

Although OS X comes with a version of Ruby, it’s sorely out of date. We can work around this issue by installing RVM.

If you’ve opted not to install oh-my-zsh, then replace zsh with bash in the command below.

zsh < <(curl -s https://rvm.beginrescueend.com/install/rvm)

Follow any prompts from the RVM install process to complete the installation. One of the final install steps for RVM is automatically loading into a shell session. You should follow the latest install step but for my copy and paste purposes those are:

  
    [[ -s "$HOME/.rvm/scripts/rvm" ]] && source "$HOME/.rvm/scripts/rvm" # This loads RVM into a shell session.
 

Close the shell and restart it in order to have RVM loaded.

Installing a Ruby Interpreter

Since I have Rails applications that I work on that still haven’t been migrated to Ruby 1.9.2, I use Ruby Enterprise Edition as my baseline Ruby install.

Install the Readline package

I’ve always installed the Readline package with my Ruby REE install, so let’s do that now.

  
    rvm pkg install readline
 

Optional Install: IConv Package

One of our projects is using the spreadsheet Ruby gem and that requires the IConv RVM package.

  
    rvm pkg install iconv
 

Installing Ruby Enterprise Edition

  
    rvm install ree --enable-shared --with-readline-dir=$HOME/.rvm/usr --patch readline-fix --with-iconv-dir=$rvm_path/usr
 

Obviously, you’ll want to discard the IConv argument if you didn’t install the RVM package. Installing a Ruby interpreter will take a while as it has to download and compile it.

As I said before, I use REE as my base Ruby install so when it’s installed, I’ll set it as my default.

  
    rvm --default use ree
 

Optional Install: Ruby 1.9.2

Although my base Ruby install is REE, I usually use Ruby 1.9.2 for any new Rails 3 applications.

  
    rvm install 1.9.2
 

Installing Database Servers

Although SQLite works for most smaller projects, MySQL and PostgreSQL are usually needed for larger projects. Installing them is easy with Homebrew.

Installing MySQL

  
    brew install mysql
 

Make sure that you follow the instructions at the end to complete the installation and setup. You can review the post install instructions at any time by using the Homebrew info command.

  
    brew info mysql
 

Installing PostgreSQL

  
    brew install postgres
 

Again, make sure that you follow the instructions at the end to complete the installation and setup. As with MySQL, you can review the post install instructions at any time by using the Homebrew info command.

  
    brew info postgres
 

Installing Base Gems

One of the cool things about RVM is that you can create gemsets. These allow you to compartmentalize your Ruby gem installs. By default, RVM creates one global gemset that others will inherit from. In this gemset, I usually apply some base gems that I want across all projects. I also install the Passenger gem at this stage. A full treatise on gemsets is beyond the scope of this guide so I urge you to read the RVM documentation for more information.

  
    gem install bundler
    gem install capistrano
    gem install capistrano-ext
    gem install git_remote_branch
    gem install open_gem
    gem install heroku
    gem install passenger
 

Installing Passenger Apache Module

Before we install Passenger, we have to update the RVM wrapper scripts. I’m not sure why installing a new instance from the Internet doesn’t include everything we need, but Passenger usually complains at the end of the install process if you haven’t done it.

  
    rvm get head && rvm reload && rvm repair all
 

Once that’s completed, finish setting up the module.

  
    passenger-install-apache2-module
 

At the end of the install process, you’ll need to let Apache know that it needs to load the module. I do this by creating a passenger.conf and pasting the code lines from the install instructions.

  
    sudo touch /private/etc/apache2/other/passenger.conf
 

You’ll need to use sudo because that directory is owned by root and you won’t be able to modify it with your account. Open the newly created file with your favorite text editor and paste in the code at the end of the install instructions. Your config file should look something similar to this:

  
    LoadModule passenger_module /Users/carlos/.rvm/gems/ree-1.8.7-2010.02@global/gems/passenger-3.0.1/ext/apache2/mod_passenger.so
    PassengerRoot /Users/carlos/.rvm/gems/ree-1.8.7-2010.02@global/gems/passenger-3.0.1
    PassengerRuby /Users/carlos/.rvm/wrappers/ree-1.8.7-2010.02@global/ruby

    # Set the default environment to development
    RailsEnv development

    # Which directory do you want Apache to be able to look into for projects?
    <Directory "/Users/carlos/work">
      Order allow,deny
      Allow from all
      Options -MultiViews
    </Directory>
 

Installing RubyCocoa and the Passenger Preference Pane

Although it’s quite old, I still use the Passenger Preference Pane for managing Rails and Rack apps. The current version requires RubyCocoa so we’ll need to install that first.

Installing RubyCocoa

  
    cd ~/
    wget http://sourceforge.net/projects/rubycocoa/files/RubyCocoa/1.0.0/RubyCocoa-1.0.0.tar.gz/download
    tar xzf RubyCocoa-1.0.0.tar.gz && rm RubyCocoa-1.0.0.tar.gz && cd RubyCocoa-1.0.0
    ruby install.rb config --build-universal=yes
    ruby install.rb setup
    # have to sudo to install this because the installer wants to copy example stuff out of the /System dir
    sudo ruby install.rb install
    cd ~/
    rm -rf ~/RubyCocoa-1.0.0
 

Once RubyCocoa has been installed, you can download the Passenger Preference Pane.

Optional Install: Pow!!

Recently, 37Signals released a zero-configuration Rack server for Mac OS X called Pow!!. This removes the need for Passenger, RubyCocoa and the Passenger Preference Pane. This project is still very young as of this writing and I haven’t had a chance to try it myself, but if you’re feeling up it, to the installation instructions and the documentation are quite good.

Ever since I installed Ruby 1.9.2-head with RVM (Ruby Version Manager) I’ve become a convert of using it to manage all of my Ruby installs.

Last week I decided to install Ruby Enterprise Edition on my development environment as my default Ruby install. My motivation for this was two-fold; better memory management and a comment by Laurent Sansonetti (one of the authors of MacRuby and works at Apple) on an article written by Robby Russell titled Installing Ruby on Rails, Passenger, PostgreSQL, MySQL, Oh My Zsh on Show Leopard, Fourth Edition.

The comment left by Laurent suggested not to rename the default Ruby install (and then symlinkling the Ruby installed via Ports) but to manage it by setting the load path.

Using RVM, we can install any Ruby version we want and have it set as the default Ruby instance easily. Let’s see how it’s done.

Note: The following documentation worked on my install of OS X. When encountering an error with the following instructions refer to the RVM documentation.

Installing the RVM Gem

There are multiple ways to install RVM, but I chose the gem install method (even if it is listed as not recommended in the documentation).

sudo gem install rvm

Installing RVM and Adding Hooks to Your Shell (bash, zsh, etc.)

Once the gem has been installed, you can now run the rvm-install command to add the hooks to your shell by running the following:

rvm-install

After RVM has been installed, you’ll be prompted to change something in your shell profile (the end of the install process will provide you with a code snippet). Since I’m using Oh My Zsh, and therefore the z shell (zsh), I opened up my .zshrc file located at /Users/carlos/.zshrc and pasted the code snippet at the bottom of the file.

Here is an example (the code snippet might be different depending on your shell and the version of RVM that was installed):

if [[ -s /Users/carlos/.rvm/scripts/rvm ]] ; then source /Users/carlos/.rvm/scripts/rvm ; fi

Updating RVM to the Latest Version

The gem version of RVM seems to be a little behind (this may be why it’s not recommended) so we’re going to update it. This updates RVM to the latest, greatest version.

rvm update --head

Installing Ruby Enterprise Edition and Dependencies

As the title of this post suggests, we’re going to be installing Ruby Enterprise Edition. According the web site, using Ruby Enterprise Edition has the potential to reduce Ruby memory consumption by 33% (on average) when used in combination with Phusion Passenger.

Before we can start installing Ruby Enterprise Edition we need to install Readline.

rvm package install readline

Once that’s done, we’re ready to get to the main event; installing Ruby Enterprise Edition.

rvm install ree -C --with-readline-dir=$HOME/.rvm/[yourusername]

Usually it will take some time for Ruby to be downloaded, compiled and properly installed with RubyGems support. When that’s done, you can switch over to your new RVM Ruby interpreter:

rvm use ree

Installing RubyCocoa for Use with the Passenger Preference Pane

Passenger is easiest to administer with the Passenger Preference Pane but it has some dependencies that we’ll have to install in order for it to work. If you don’t wish to manage virtual hosts with the Passenger Preference Pane, you can skip down to the next section.

Installing RubyCocoa

At the time of this writing, RubyCocoa 1.0.1 has been released but it’s broken at this time so we’ll have to rely on RubyCocoa 1.0.0.

Let’s download this from source and build it:

tar xzf RubyCocoa-1.0.0.tar.gz && rm RubyCocoa-1.0.0.tar.gz && cd RubyCocoa-1.0.0

ruby install.rb config --build-universal=yes
ruby install.rb setup
sudo ruby install.rb install

To make sure that RubyCocoa you’ll need to pop open an IRB session:

irb
require 'osx/cocoa'

If everything has gone well, you’ll see the shell return ‘true’ and you’re ready to install the Passenger Preference Pane

Installing and Configuring Passenger

Note: If you already had a development environment up and running, you’ll need to re-install your gems into the new RVM’d environment. When installing a gem into an RVM’d environment, do not prepend the command with sudo.

Before we can install Passenger, we’ll need to generate some wrapper scripts. This is done with the following:

rvm ree --passenger

Since the Ruby Enterprise Edition suggests using it with Passenger, we’ll go ahead and install the gem now.

gem install passenger

Once the gem has been installed, we need to to make sure that Apache is running; open up the System Preferences and then the Sharing applet. Make sure that Web Sharing is checked. Doing so will start the Apache web server.

Since Apache has been installed we need to have Passenger and Apache be friends. Start off by adding the Passenger module to Apache:

rvmsudo passenger-install-apache2-module

Towards the end of the installation process, you’ll be prompted to copy some information to put into your Passenger configuration file. There is a catch though, the Passenger install has no idea that you’re using RVM so the last two lines have inaccurate information (they are most likely referencing your system Ruby instance). The fix for this is easy though, you’ll just have to change the references to point to your RVM’d instance instead.

Here is an example from my install (obviously you’ll want to replace [yourusername] with your actual username:

LoadModule passenger_module /Users/[yourusername]/.rvm/gems/ree-1.8.7-2010.01/gems/passenger-2.2.11/ext/apache2/mod_passenger.so
PassengerRoot /Users/[yourusername]/.rvm/gems/ree-1.8.7-2010.01/gems/passenger-2.2.11
PassengerRuby /Users/[yourusername]/.rvm/bin/passenger_ruby

As mentioned, the above code snippet needs to be added to a passenger configuration file which I normally put in /private/etc/apache2/other and I call the file passenger.conf. I should note that this directory is owned by root, so when you create the file and save it you’ll have to provide your system password in order to make the changes.

Here is a sample of my configuration file:

LoadModule passenger_module /Users/carlos/.rvm/gems/ree-1.8.7-2010.02/gems/passenger-2.2.14/ext/apache2/mod_passenger.so
PassengerRoot /Users/carlos/.rvm/gems/ree-1.8.7-2010.02/gems/passenger-2.2.14
PassengerRuby /Users/carlos/.rvm/bin/passenger_ruby

#Set the default environment to development
RailsEnv development

# Which directory do you want Apache to be able to look into for projects?
<Directory "/Users/carlos/work">
	Order allow,deny
	Allow from all
</Directory>

Finishing Up

If you’d like to make Ruby Enterprise Edition your default Ruby Interpreter, just use the following command:

rvm ree --default

Once Passenger has been configured, all that’s left to do is restart Apache. You can restart Apache by going to the System Preferences Pane and selecting the Sharing applet. Uncheck and re-check Web Sharing.

You should now be able to add Rails and Rack applications with the Passenger Preference Pane. Note: When opening the Passenger Preference Pane, you might see this warning:

This is normal if you have a 64-bit machine. Since RubyCocoa is 32-bit, it just has to relaunch the preference pane.

RVM is a fast moving target and as such these installation instructions may be out of date by the time you read them. I try to update my older posts when I get new information, but if you stumble across something that doesn’t work or if you know of a better way of doing something, please let me know.

This article is still valid, but there is a newer one available. I recommend checking it out.

Snow Leopard, Apple’s latest release of their OS X Operating System, was released last month. I pre-ordered it from Amazon but it’s only now that I’ve gotten around to installing it on my machines. I first installed it on my Mac Mini as a fresh install and because of that, I wanted to document the process. I probably could have upgraded Leopard to Snow Leopard, but I didn’t want 32bit binaries floating around where I could have been using a 64bit binary.

Determining whether or not your Mac is 64bit or 32bit is based on the processor. Click on the Apple logo in the menu bar and choose About This Mac. Look at the processor type. If it’s a Core Duo, you have a 32bit Mac, if it’s a Core 2 Duo then you have a 64bit Mac. Keep that in mind when installing applications like RubyGems and database drivers.

One more thing, with this guide, I stuck with MacPorts for some application installs. I know that Homebrew is all the rage nowadays, but I’ve had little to no trouble using MacPorts, so that’s what I’ve stuck with.

Installing XCode

This whole process breaks down if you don’t install XCode, so go ahead an do that now. You could probably download it online but since the Snow Leopard DVD is only a month old (at the time of this writing), go ahead an install it from there.

Just in case you’ve never installed XCode, it’s located on the DVD in the Optional Installs directory. Just run the Xcode.mpkg installer. Choose the default settings for the installation.

Installing MacPorts

Head on over to the MacPorts site and download the dmg disk image for Snow Leopard. Once the download is complete, run the installer from the mounted disk image. I chose the defaults through the installation process.

The Snow Leopard version of MacPorts should modify your $PATH automatically so that you can run “port” commands from the Terminal without having to prefix it with the location path of the MacPort binaries. If you want to make sure, you can run this command from the Terminal:

cat ~/.profile

You should see something similar to this:

# MacPorts Installer addition on 2009-10-08_at_19:43:18: adding an appropriate PATH variable for use with MacPorts.
export PATH=/opt/local/bin:/opt/local/sbin:/usr/local/bin:$PATH
# Finished adapting your PATH environment variable for use with MacPorts.

If you don’t see this, you’ll want to edit your path to include /opt/local/bin and opt/local/sbin. You can do this by opening your .profile file with TextEdit and make the changes:

sudo '/Applications/TextEdit.app/Contents/MacOS/TextEdit' ~/.profile

Add the following lines before “$PATH”:

/opt/local/bin:/opt/local/sbin:/usr/local/bin:

Now you should be able to run the command

which port

and see the output

/opt/local/bin/port

MacPorts should correctly compile the correct version (32bit vs 64bit) of applications and libraries for you based on your CPU (confused about which Mac version you have?). If you’re feeling paranoid and want to force it to always use a certain mode, you can use your favorite text editor and edit the file at:

/opt/local/etc/macports/macports.conf

Example:

open -e /opt/local/etc/macports/macports.conf

Look in the file for the commented out “build_arch” declaration. If you want to force 64bit mode for example, you’d uncomment the line and change the value to x86_64.

Ruby, Rails, and Gems

Snow Leopard, like it’s predecessor comes bundled with a version of Ruby, Rails, and RubyGems. Since I’ve been using Rails professionally, I always like to install my own version of Ruby and RubyGems from MacPorts. I also like to download Rails from the gem source myself.

Before we can do that, we should hide the versions that come pre-bundled with Snow Leopard.

You can do that by running the following commands in the Terminal (inputting your password where requested):

sudo mv /usr/bin/ruby /usr/bin/ruby.orig
sudo mv /usr/bin/gem /usr/bin/gem.orig
sudo mv /usr/bin/rails /usr/bin/rails.orig

Finally we’re ready to install Ruby and RubyGems via MacPorts. Just run the following from the Terminal:

sudo port install ruby rb-rubygems

This will take a while, so you might want to take a break and stretch your legs while it’s doing its business. Once Ruby and RubyGems have been installed, you can go ahead and install Rails itself.

sudo gem install rails

Installing Your Database Servers

I use both PostgreSQL and MySQL but you don’t have to install them. In fact, since Rails uses SQLite for development (by default) you might not need to install either of them. With that being said, I highly recommend to install both database servers just in case you need to use them.

Installing both is quite trivial but make sure to pay attention to the output at the end of the commands as it has text that you’ll want to copy and paste into your Terminal. Run the following commands for PostgreSQL:

sudo port install postgresql84 postgresql84-server

Again, make sure you read the post install text as it’ll direct you to install a default database, create a default postgres user, and setup PostgreSQL to start automatically at start up. (recommended).

Once you’ve run the commands that it has suggestion, it’s a good time to add PostgreSQL to your path so that you can install the database driver. Again, open your .profile and edit your path and add the following right before “$PATH”.

/opt/local/lib/postgresql84/bin/:

Install the PostgreSQL Rails database driver by running the command:

sudo env ARCHFLAGS="-arch x86_64" gem install pg

If you want to install the 32bit driver, then you can just run:

sudo gem install pg

Installing MySQL is as simple as installing PostgreSQL. In the Terminal:

sudo port install mysql5 mysql5-server

Just like in the PostgreSQL install, make sure you read the post install text. It’ll have you setup a default database, and will give you a command so that MySQL can load at start up (recommended).

After MySQL has been installed you’ll want to install the MySQL database driver for Rails:

sudo env ARCHFLAGS="-arch x86_64" gem install mysql -- --with-mysql-config=/opt/local/lib/mysql5/bin/mysql_config

If you want the 32 version:

sudo env ARCHFLAGS="-arch i386" gem install mysql -- --with-mysql-config=/opt/local/lib/mysql5/bin/mysql_config

By default, MySQL likes to use UNIX sockets for communication and therefore it needs a .sock file. I usually like to store mine in /tmp/mysql.sock. It doesn’t exist by default, so you’ll have to create it:

sudo touch /tmp/mysql.sock

After that file has been created you’ll have to tell MySQL to use your newly created socket file:

sudo touch /opt/local/etc/mysql5/my.cnf
sudo '/Applications/TextEdit.app/Contents/MacOS/TextEdit' /opt/local/etc/mysql5/my.cnf

Add the following to the my.cnf file:

[mysqld_safe]
socket=/tmp/mysql.sock

[client]
socket=/tmp/mysql.sock

PostgreSQL and MySQL should now be installed but you’ll want to install the SQLite database driver gem. It’s dead simple:

sudo gem install sqlite3-ruby

Installing Your Web Server

I use Passenger for my development web server and I highly recommend you doing the same. It’s not necessary, so you can certainly skip the step if you’d like.

Before we start installing anything, let’s turn on Apache. Go to the Sharing Preference pane under System Preferences and check Web Sharing. This should activate Apache.

Let’s install the Passenger gem and the Apache 2 module:

sudo gem install passenger
sudo passenger-install-apache2-module

Make sure that you read the text after the Apache module has been installed. It will give you lines of text that you’ll need to copy into your Apache config file.

Here is a sample of mine:

# Passenger modules and configuration
LoadModule passenger_module /opt/local/lib/ruby/gems/1.8/gems/passenger-2.0.6/ext/apache2/mod_passenger.so
PassengerRoot /opt/local/lib/ruby/gems/1.8/gems/passenger-2.0.6
PassengerRuby /opt/local/bin/ruby

I create a Passenger specific config file to hold this information:

sudo touch /etc/apache2/other/passenger.conf

Open the newly created file in TextEdit (you know the drill here sudo ‘/Applications/TextEdit.app/Contents/MacOS/TextEdit’ /etc/apache2/other/passenger.conf) and copy the lines from the post Apache 2 module install as well as some additional text. Here is a sample from my passenger.conf file:

# Passenger modules and configuration
LoadModule passenger_module /opt/local/lib/ruby/gems/1.8/gems/passenger-2.0.6/ext/apache2/mod_passenger.so
PassengerRoot /opt/local/lib/ruby/gems/1.8/gems/passenger-2.0.6
PassengerRuby /opt/local/bin/ruby

# Set the default environment to development
RailsEnv development

# Which directory do you want Apache to be able to look into for projects?
<Directory "/Users/carlos/work">
    Order allow,deny
    Allow from all
</Directory>

You’ll obviously want to replace the path “/Users/carlos/work” with your own. This path doesn’t have to be specific as we’ll be using the Passenger Preference Pane to tell it where are projects are at.

Since the Passenger Preference Pane relies on Ruby Cocoa, we’ll need to install before we start to configure it.

NOTE: The Passenger Preference Pane is 32bit only so you’ll get a warning that the System Preferences has to relaunch in 32bit mode when you try to run it. It doesn’t negatively affect anything but it’s still a minor annoyance. Once MacRuby is stable enough it’ll be ported there and the warnings will go away.

Installing Ruby Cocoa is a simple port install:

sudo port install rb-cocoa

You might get errors setting up your projects using the Passenger Preference Pane because it expects to find the Snow Leopard bundled version of Ruby. Since we installed our own, I just trick it by running the command:

sudo ln -s /opt/local/bin/ruby /usr/bin/ruby

Next, download and install the latest Passenger Preference Pane (as of this writing it’s version 1.3). Adding projects to your Passenger Preference pane should be simple as it’s all GUI driven. When choosing a project path, just point it to the root directory of the project and it’ll figure out the rest.

Even though I prefer Passenger for development mode, it’s still handy to install Mongrel (and simple too).

sudo gem install mongrel

Parting Thoughts

At this point, you should have a working development environment for Ruby on Rails. I’ve tried to distill my notes into something readable just in case someone comes across this. If you have any problems with the steps above, feel free to ask a question in the comments.