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.
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.
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:
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.
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:
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
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
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
echo bundler >> ~/.rbenv/default-gems
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
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]
Now that your Ruby environment is ready to go, install the Rails gem:
gem install rails --no-document
And now you’re all done!
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.
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