55 Minutes

Welcome to the 55 Minutes blog.
55 Minutes is a web development consultancy in San Francisco building apps for design-led businesses and startups. On this blog we discuss the technology tools of our trade: Ruby on Rails, Django, Sass, OS X, and more.

Rails OS X Developer Guide Installing an rbenv-based Rails stack on Mavericks and Mountain Lion

If you’re like me, you have multiple Rails projects in flight at any given time. You want a no-nonsense development environment that gets out of your way so you can get your work done. Note: This guide was updated on October 14th, 2013 to include Mavericks instructions.

This guide explains how to set up a Rails development environment with these goals:

Sound good? Let’s get started.

1. Check the prerequisites

This guide assumes you will be doing all your development using a single administrator account on your Mac. If you share your Mac with multiple accounts, or you develop using a non-admin account, these instructions may not work.

I’m also assuming that you are running OS X Mavericks (10.9) or OS X Mountain Lion (10.8.5) and have installed all the latest software updates.

Note that this tutorial offers slightly different instructions for Mavericks vs Mountain Lion, so read carefully.

2. Install command-line tools

To be able to use homebrew for installing packages like Ruby and PostgreSQL, you’ll need Apple’s command-line tools package, which is not installed by default.


Mavericks will helpfully offer to install the command-line tools for you. Simply open Terminal and run:


A window will appear asking if you want to install the command-line tools. Click Install. It’s that easy! Download and installation should only take a few minutes.

Mavericks command-line tools window

Mountain Lion

On Mountain Lion, the easiest way to get the command-line tools is through Xcode.

Download Xcode (Mac App Store). It’s free. The download weighs in at almost 2GB, so give yourself some time for this step. Once downloaded, launch Xcode to complete the installation.

Then, open the Xcode preferences and click the Downloads tab. Find Command Line Tools and click install.

3. Install homebrew

Homebrew is a popular package manager that allows you install newer and better versions of command-line utilities like git, databases like PostgreSQL, and native libraries needed for compiling Ruby and various gems. Install it by running this command and following the instructions when prompted:

ruby -e "$(curl -fsSL https://raw.github.com/Homebrew/homebrew/go/install)"

Double-check that everything installed OK by running:

brew doctor

Add homebrew/dupes to take advantage of homebrew packages that replace the Mac built-ins:

brew tap homebrew/dupes

Now install all the packages needed for Ruby development (it may take several minutes for these to download and compile):

brew install apple-gcc42 autoconf pkg-config git postgresql qt

4. Install rbenv

Rbenv is a tool for maintaining and switching between Ruby versions on the command-line. This lets you leave the standard OS X version of Ruby alone (it is the ancient 1.8.7) and use newer versions of Ruby easily and safely.

Since rbenv itself is modular and extremely simple, the real power of rbenv is its plugin system. Here are the plugins I recommend:

The rbenv-installer project helpfully installs rbenv and all of these recommended plugins for you. Just run:

curl -L https://raw.githubusercontent.com/fesplugas/rbenv-installer/master/bin/rbenv-installer | bash

To complete the installation, you’ll need to add these lines to your ~/.bash_profile:

export RBENV_ROOT="$HOME/.rbenv"

if [ -d $RBENV_ROOT ]; then
  export PATH="$RBENV_ROOT/bin:$PATH"
  eval "$(rbenv init -)"

Next, there are two gems that you’ll want as a baseline for all versions of Ruby: bundler and rubygems-bundler. Bundler manages gem dependencies for Rails applications, and rubygems-bundler improves upon bundler by making the bundle exec behavior automatic.

echo bundler >> ~/.rbenv/default-gems
echo rubygems-bundler >> ~/.rbenv/default-gems

Finally, restart your shell by opening a new Terminal window or tab. This will ensure that rbenv has loaded.

5. Compile Ruby

With rbenv and the ruby-build plugin installed, the compiler packages from homebrew, and the toolchain from Xcode, you now have all pieces in place for compiling any version of Ruby.

The latest stable version of Ruby is 2.1.2. Install it like this:

CFLAGS=-O3 rbenv install 2.1.2

Be patient; this will take 5–10 minutes depending on your CPU.

When that’s done, tell rbenv that you’d like 2.1.2 to be the default version whenever you use ruby, irb or gem on the command-line.

rbenv global 2.1.2

Test that it worked:

ruby -v

Finally, don’t forget to enable rubygems-bundler, so that you never have to type bundle exec:

gem regenerate_binstubs

6. Configure PostgreSQL

PostgreSQL was installed via homebrew back in step 3, but there are a couple more steps needed to set it up.

Initialize the database:

initdb /usr/local/var/postgres -E utf8

Configure PostgreSQL to run automatically on startup:

mkdir -p ~/Library/LaunchAgents
ln -sfv /usr/local/opt/postgresql/*.plist ~/Library/LaunchAgents
launchctl load ~/Library/LaunchAgents/homebrew.mxcl.postgresql.plist

And now you’re all done!

Maintaining your environment

The Ruby community moves quickly, and it is good to stay up to date. Make a habit of updating homebrew and rbenv regularly:

rbenv update
brew update
brew upgrade

When a new version of Ruby is announced, first update rbenv to make sure you have the latest ruby-build definitions, then follow the instructions in step 5 above to compile the new Ruby.

Starting a Rails project

Now that your environment is ready to go, grab Rails and start a new project in the normal way:

gem install rails --no-document
rbenv rehash
rails new myproject -d postgresql -T

Or consider using the 55 Minutes rails-starter template to hit the ground running with SMACSS, LiveReload, Rspec, Capybara, Capistrano, and much more.

Have fun!

comments powered by Disqus