Rails OS X Setup Guide

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. This guide explains how to set up a Rails development environment with these goals:

• Install easily onto a stock Mac running OS X 10.9+.
• Automatically switch Rubies per project.
• Use Bundler for managing gems. No need to reinvent the wheel with gem sets.
• Prefer Homebrew, rbenv, PostgreSQL, Git, bash.
• Rails 3.2 and higher.

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 El Capitan (10.11), OS X Yosemite (10.10), or OS X Mavericks (10.9), and have installed all the latest software updates.

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. To download them, simply open Terminal and run:

git

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.

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:

/usr/bin/ruby -e "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/master/install)"

Double-check that everything installed OK by running:

brew doctor

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

brew install homebrew/dupes/apple-gcc42 autoconf phantomjs pkg-config git postgresql qt55

Configure PostgreSQL to run automatically on login:

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

Note that Apple no longer ships OpenSSL headers with El Capitan. So if you are using El Capitan you’ll need to run these extra steps:

brew install openssl
brew link openssl --force

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 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:

• ruby-build is responsible for downloading and installing Ruby.
• rbenv-default-gems allows you to specify a list of gems you want for all your Ruby environments. Whenever you install a new Ruby via ruby-build, your desired gems are automatically installed with it.

Rbenv is available through Homebrew, so installing it and its plugins is simple. Just run:

brew install rbenv rbenv-default-gems ruby-build

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

eval "$(rbenv init -)"

Next, restart your shell by opening a new Terminal window or tab. In the new shell, verify that rbenv is installed and loaded by running the rbenv doctor, like this:

curl -fsSL https://github.com/rbenv/rbenv-installer/raw/master/bin/rbenv-doctor | bash

You should see this output:

Checking for `rbenv' in PATH: /usr/local/bin/rbenv
Checking for rbenv shims in PATH: OK
Checking `rbenv install' support: /usr/local/bin/rbenv-install (ruby-build 20151230)
Counting installed Ruby versions: none
  There aren't any Ruby versions installed under `/Users/mbrictson/.rbenv/versions'.
  You can install Ruby versions like so: rbenv install 2.2.4
Checking RubyGems settings: OK
Auditing installed plugins: OK

Finally, there is one gem that you’ll want as a baseline for all versions of Ruby: Bundler, which manages gem dependencies for Rails applications. The rbenv-default-gems plugin will install it automatically so you never forget; just add it to the default-gems file.

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

5. Compile Ruby

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

As I write this, the latest stable version of Ruby is 2.3.1. Install it like this:

CFLAGS=-O3 rbenv install 2.3.1

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

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

rbenv global 2.3.1

Finally, test that it worked:

$ ruby -v
ruby 2.3.1p112 (2016-04-26 revision 54768) [x86_64-darwin15]

6. Install Rails

Now that your Ruby environment is ready to go, install the Rails gem:

gem install rails --no-document

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 regularly:

brew update
brew upgrade

When a new version of Ruby is announced, first update Homebrew 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

To create a Rails project, just use the rails new command, like this:

rails new myproject -d postgresql

Or consider using my rails-template to hit the ground running with LiveReload, Minitest, Capybara, Capistrano, and much more.

rails new myproject \
  -d postgresql \
  -m https://raw.githubusercontent.com/mattbrictson/rails-template/master/template.rb

Have fun!