Boss guide to installing Ruby on Rails

Manfred Stienstra

Every once in a while my boss asks me for help getting a Rails project running on his shiny new MacBook Pro. I’ve made him this guide to make sure he won’t waste my time again. It might come in handy for your boss too.

Please note that we assume the machine is running a clean install of Mac OS X Mountain Lion (10.8).

Install Xcode

Launch the App Store and use it to install Xcode. Start Xcode and follow the directions to complete the installation. Then choose Preferences from the Xcode menu and click the Downloads tab. Install the Command Line Tools.

The Download tab in Xcode’s Preferences.

The Download tab in Xcode's Preferences.

Grab something to drink and watch your favorite YouTube video. We’ll have to wait for this to download before we can continue.

Install Ruby

First, enter this command in the Terminal to make sure the default Xcode location is set:

sudo xcode-select --switch /Applications/Xcode.app

We’re going to use rbenv to compile and manage Ruby versions. Even when you’re planning to use a single version of Ruby, this is still the easiest way to set it up. The rbenv instructions suggest we use Homebrew, so we’ll get that first:

ruby -e "$(curl -fsSkL raw.github.com/mxcl/homebrew/go)"
brew tap homebrew/dupes
brew install apple-gcc42
brew install git rbenv rbenv-gemset ruby-build
echo 'eval "$(rbenv init -)"' >> ~/.bash_profile

Now quit and then open your Terminal again to make sure your bash profile gets reloaded. For this example we’re going to install Ruby 1.9.3:

rbenv install -list
rbenv install 1.9.3-p194
rbenv rehash

Get your Rails app running

It’s reasonable to assume your Rails app runs at least version 3 and that you’re using Bundler for dependency management. The rbenv gemsets feature allows us to isolate a set of gems specifically for our project. We start by configuring the Ruby version and the name of the gemset for this application (replace “[project-name]” with the directory name of your Rails project):

cd [project-name]
echo "[project-name]" > .rbenv-gemsets
echo "1.9.3-p194" > .rbenv-version

Now make sure everything worked and is in the right place:

which gem

This should return /Users/[your-username]/.rbenv/shims/gem. We’re ready to install the dependencies for your Rails app:

gem install bundler
rbenv rehash
hash -r
bundle install

Troubleshooting compilation problems

Compilation might fail when one of the dependencies is using Quartz (i.e. ImageMagick) and the X11 directory isn’t in the library load path. The easiest way to fix this is with a symlink:

ln -s /opt/X11 /usr/X11

Reader questions

Javier Vázquez from Zürich, Switserland would like us to explain how to install PostgreSQL.

The easiest way is to install Postgres.app. You can download it from postgresapp.com. After that you configure it in config/database.yml like so:


development:
  adapter: postgresql
  encoding: unicode
  database: [project-name]_development
  min_messages: warning
test:
  adapter: postgresql
  encoding: unicode
  database: [project-name]_test
  min_messages: warning
  

Example database configuration.

Don't forget to replace [project-name] with your project name.