This guide explains how to set up a Rails development environment with these goals:
- Install easily onto a stock Mac running OS X Mavericks or Mountain Lion.
- Automatically switch Rubies per project.
- Use Bundler for managing gems. No need to reinvent the wheel with gem sets.
- But don’t make me type
- 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 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.
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:
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:
- 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-update gives you the
rbenv updatecommand, which updates rbenv and all of your plugins to the newest versions in one step.
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
export RBENV_ROOT="$HOME/.rbenv" if [ -d $RBENV_ROOT ]; then export PATH="$RBENV_ROOT/bin:$PATH" eval "$(rbenv init -)" fi
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
gem on the command-line.
rbenv global 2.1.2
Test that it worked:
Finally, don’t forget to enable rubygems-bundler, so that you never have to type
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