tech projects and more


The right way to set up a ruby/rails environment on OS X

I recently decided to delve into the popular web-development language, Ruby on Rails. I was ready to start playing around with some code asap, but I quickly learned that setting up a proper environment was a project (and a potential headache) in itself. There are a lot of different ways to get the required software on your workstation, some much cleaner than others. After taking a few missteps myself I eventually ended up with a really beautiful, efficient and custom development environment:

In this update I'll walk you through properly installing and customizing your own ruby environment on OS X. I will assume that you're working with a clean install of Snow Leopard, but if you're not then you may want to remove some older tools or even start off fresh with a new install (I took the latter route).

Step 0: Remove MacPorts if it's installed

This one is for those who aren't starting out clean. Run these commands to remove MacPorts if it's installed.

sudo port -f uninstall installed

sudo rm -rf /opt/local \
/Applications/MacPorts \
/Applications/DarwinPorts \
/Library/Tcl/macports1.0 \
/Library/Tcl/darwinports1.0 \
/Library/LaunchDaemons/org.macports.* \
/Library/StartupItems/DarwinPortsStartup \
/Library/Receipts/MacPorts*.pkg \
/Library/Receipts/DarwinPorts*.pkg \

Step 1: Install XCode Developer Tools.

Chances are you've already got these installed, but if you're just starting out in the development world this may be new to you. The development tools are available from Apple for free and can be found here:

These tools are a prerequisite for many other programming languages and projects on OS X as well. Be sure that you install X11 along with XCode, this is an option given during the installation process. Unfortunately as of XCode version 4, Apple has started charging $5. XCode 4 can be found through Apple's developer portal or through their desktop "App Store" application.

Step 2: Install SIMBL

SIMBL is a package that allows patching of existing OS X applications. In this tutorial we'll be using SIMBL to patch Terminal to allow advanced color schemes and plugins. SIMBL can be found here:

Step 2.1: (OPTIONAL) Enable 64-bit mode Snow Leopard

By default Snow Leopard boots into 32-bit mode, and on many macs it is not even possible to boot into 64-bit mode (a 64-bit kernel requires 64-bit drivers, which do not exist for all macs with 64-bit capable chips). Why would one want to enable 64-bit mode on Snow Leopard? Well, many won't.

Snow Leopard is still capable of delivering 64-bit applications on a 32-bit kernel, which includes all the commonly used applications such as Finder, iTunes, iPhoto, so on. In most ways, the bit-ness of your Snow Leopard install doesn't matter. Benchmarked systems running both kernels have shown that 64-bit mode offers a slight increase in memory performance, and a slight decrease in overall performance. For some reason this didn't deter me, I guess I just love the idea of running my kernel in a "proper" 64-bit fashion. If I haven't convinced you not to, follow these instructions to enable 64-bit mode.

To enable 64-bit kernal and extensions you can either reboot and hold down the "6" and "4" keys for a one time boot or you can do a little plist editing to turn it on by default. So that I'm not just reposting other guides there's an excellent walkthrough on this here

Step 3: Install Homebrew Package Manager

There are a number of package managers for OS X available out there, the heavy hitters being Fink, MacPorts and Homebrew. I have tried all of these and can say that Homebrew is the easiest and lightest environment I've found and I switched over from MacPorts the day I found it. Unlike MacPorts and Fink, Homebrew integrates with the core operating system which reduces the number of additional libraries one has to install.

Run these commands to create and take ownership of /usr/local if you don't already have it:

sudo mkdir /usr/local
sudo chown -R $USER /usr/local

Installation is done with this command:

ruby -e "$(curl -fsSLk"

This installs homebrew in the default configuration, which assuming you've got a clean system or /usr/local, will be the preferable way as we want to use brew without sudo whenever possible.

Step 4: Install git and update brew

brew install git
brew update

Step 5: Install zsh if you want

I have switched from bash to zsh as it's got pretty much all the features as bash but with a greater feature set. If you're used to bash then zsh won't be unfamiliar to you and you'll probably be very happy with the added features. Here's a quick overview of features it has over other shells such as bash:

brew install zsh

Set zsh as default:

Open System Preferences > Accounts (click the lock if it's in "locked" mode and authenticate)
Right click on the account name you'd like to change in the left hand column and click "Advanced Options"
Select the default shell in the dropdown menu as /bin/zsh and click OK

Step 6: Install oh-my-zsh (if zsh was installed)

This set of dotfiles is pretty incredible. It allows for a large number of plugins and themes to be applied to your zsh environment and is incredibly customizable. If you decide to customize it heavily, fork it so others can enjoy your work. At the time of writing oh-my-zsh is the 7th most forked project on github.

Unfortunately Apple didn't see it fit to include wget, our method for install oh-my-zsh, in Snow Leopard for some reason. To rectify this travesty, install wget with:

brew install wget

Then install oh-my-zsh with this command:

wget -O - | sh

Step 6.1: Customize oh-my-zsh

If you decided to install oh-my-zsh (any why wouldn't you?) here is one quick modification that you may find handy:

in ~/.oh-my-zsh/custom/shortcuts/zsh you are able to define terminal shortcuts. I currently have only two very simple shortcuts, but I use them multiple times a day. the contents of my shortcuts.zsh file is below:

# Add yourself some shortcuts to projects you often work on

This creates two shortcuts. When I type c into the command line, I am taken to my code directory, which I keep in ~/Code. Typing h takes me to my home directory.

Step 7: Install Visor

This one isn't necessary for a quality development environment but after trying it out I can't go back to typical terminals. It's a very cool, always-accessible terminal overlay. Try it out and I think you'll be happy you did.

The binary can be found here:

Step 8: Install your text editor of choice (TEXTMATE!)

Although you could use another text editor for ruby/rails development, textmate is a common choice. It's not cheap (€39, $54)but it's also worth every penny. Textmate can be found here:

On first run textmate will ask if it should install the mate terminal command. This is very useful and I would highly recommend it.

Of course one could use any of the many other text editors available out there, including the very popular and free emacs/xemacs or vi/vim editors.

Step 9: Install Ruby Version Manager

We could potentially install ruby through hombrew but using rvm allows for multiple ruby installs to be easily managed and switched between.

bash < <( curl )

Now we need to load rvm into shell sessions by default. As we're using zsh just past this line into ~/.zshrc or if you're sticking with bash then load it into ~/.bash_profile

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

As we've got textmate installed you can easily edit these files with the command:

mate ~/.zshrc

now we want to check to make sure that rvm is properly installed. Run the following command:

type rvm | head -1

If rvm was installed correctly you'll see

rvm is a function
Step 10: Install Ruby versions

The three most popular ruby versions are 1.8.7, 1.9.2 and Ruby Enterprise Edition. Let's install all three, why not?

We're going to install these with readline support to allow easier editing from the command line. While Ruby comes with readline support through libedit, there are some odd hickups that occur when using certain shortcuts like ctrl+c. To install proper readline support type:

rvm package install readline

and then to install our ruby versions with readline support:

rvm install 1.9.2 --with-readline-dir=$HOME/.rvm/usr
rvm install 1.8.7 --with-readline-dir=$HOME/.rvm/usr --patch readline-fix
rvm install ree --with-readline-dir=$HOME/.rvm/usr --patch readline-fix

ruby versions can be switched with the command

rvm 1.8.7

or whatever version you would like to switch to. Let's also set a version as default:

rvm 1.9.2 --default

This command will also tell your system to use the version of ruby installed with rvm instead of the version that comes packaged with OS X.

Step 11: Install Rails

As we've installed our environment as user, gem commands don't need sudo attached to them.

gem install rails

Step 12: Make it Pretty

We've installed a number of plugins to improve the look of our rails environment, now let's put those to use. My favorite textmate theme is railscasts, a custom one built specifically for rails. This is available from the railscasts page here:

I personally am a big fan of the Inconsolata font for programming. It can be found here:
another popular font that looks pretty nice with rails/textmate is Droid Sans Mono. It can be found here: Try these out and see what you like!

The real beauty in our oh-my-zsh terminal comes from the oh-my-zsh themes. I have made my own oh-my-zsh theme based on the default with a number of enhancements and customizations. It's nice to have some sense of congruency between textmate and the terminal. The color scheme in my theme uses similar colors as the textmate railscasts theme with a few changes to enhance readability. You should play around with this and see what you like, but if you want to use the theme I put together it is available here: phossil-theme




Appendix: Getting Started with Rails Resources

Here are a few awesome resources that have been an incredible help to me and my time with rails:

Why's Poignant Guide to Ruby: This should be a pre-req for anyone looking to learn a ruby based language. While not specifically about rails, this short guide presents an intro to ruby in a hilarious, informative and truly bizarre way.

GitReady: a nice resource when trying to learn the ins and outs of using Git.

GitHub: THE online Git repository. There are endless ruby/rails examples here, tons of opportunities to share your project or fork someone else's (not to mention it being the most popular version manager among rails developers)

Agile Web Development with Rails: If you must pay for a book on rails, you can't go wrong with this one. This version covers rails 3.x (see the 3rd edition for rails 2.x) and is available in PDF form or physical book. I have to say I'm a big fan of the Pragmatic Bookstore too, I pre-ordered the physical book and they sent me "beta" versions of the PDF to tide me over until the physical book release date.

Railscasts: This site has incredible webcasts discussing all aspects of working with rails. After you're fairly stable on your feet with rails give it a look.

Filed under: Ruby on Rails 2 Comments