Jens Ljungblad

Setting Up a Ruby on Rails + Postgres Environment on OS X

This post describes how to set up a Ruby on Rails + Postgres environment for local development. It is a particularly suitable combination if you want to deploy to the Heroku platform. This has been tested to work on Lion, Mountain Lion and Mavericks. While some of the tools described are OS X specific, the bulk of the post applies to Linux as well. Whatever system you’re on, make sure it’s running the latest everything before you get started.

Updated on Jul 23rd, 2014

Begin by installing Homebrew, an easy to use package manager for OS X:

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

Homebrew works by symlinking all binaries to usr/local/bin, thus you need to make sure it is placed before usr/bin in your path. If it’s not, put the following in your .bash_profile or similar:

1
export PATH=/usr/local/bin:$PATH

Note: If you have problems compiling packages, run brew doctor for troubleshooting tips. If it complains about not finding gcc, make sure you have installed Xcode from the App Store. Launch it, go to Preferences, choose the Download tab and grab the Command Line Tools.

After installing packages with Homebrew it will usually spit out a bunch of useful information. You can always read this later by running:

1
$ brew info [package]

Ruby, Rails and Bundler

I am a fan of Sam Stephenson’s rbenv, a tool which lets you easily switch between multiple versions of Ruby. It’s simple, unobtrusive, and follows the UNIX tradition of single-purpose tools that do one thing well. In order for it to work, you need to get rid of rvm, if installed:

1
$ rvm implode

Installing rbenv is easy, and while you’re at it, also install ruby-build, a plugin which simplifies the process of installing new Ruby versions. Use Homebrew to grab both:

1
2
3
$ brew update
$ brew install rbenv
$ brew install ruby-build

Add rbenv init to your .bash_profile to enable both shims and autocompletion:

1
$ echo 'eval "$(rbenv init -)"' >> ~/.bash_profile

Install the version(s) of Ruby that you need for your projects using the install command that is added by ruby-build:

1
$ rbenv install 2.0.0-p247

Using rbenv it is possible to set a per-project Ruby version using the rbenv local [version] command. This will generate a .ruby-version file, which can be put under version control. By doing this, rbenv will automatically switch to the correct Ruby version when you navigate among your projects.

1
2
3
4
5
$ mkdir ~/projects/myproject
$ cd ~/projects/myproject
$ rbenv local 2.0.0-p247
$ ls -a | grep ruby-version
.ruby-version

If you want something other than the bundled OS X Ruby version available throughout your system, setting a global version is a good idea:

1
$ rbenv global 2.0.0-p247

Bundler is a dependency manager for Ruby. It’s one of few gems you’ll need to install using RubyGems, as most project specific gems can be installed and updated using Bundler itself. Another gem we’ll install right away is Rails. Run the following:

1
2
3
$ gem install bundler
$ gem install rails
$ rbenv rehash

Note: You need to run rbenv rehash whenever you have installed gems that come with binaries. If you think this is an annoyance, install rbenv-gem-rehash using Homebrew:

1
$ brew install rbenv-gem-rehash

Let’s set up a Rails app:

1
2
$ cd ~/projects/myproject
$ rails new . --database postgresql

Rails has now created a Gemfile, which is a list of project dependencies to be installed by Bundler. Install them:

1
$ bundle install

Postgres

I previously used Homebrew to install Postgres which is perfectly fine, but I have since discovered the excellent Postgres.app by Mattt Thompson, which is dead easy to set up. Download, extract, launch. You now have Postgres running on port 5432, and a cute elephant to control it in your menu bar. Wasn’t that easy?

Note: If you have Postgres previously installed via Homebrew, you should remove it for Postgres.app to function properly:

1
$ brew remove postgresql

Postgres comes with a bunch of command line utilities, which are all bundled up inside Postgres.app. To access them from the Terminal, add their location to your path by modifying your .bash_profile:

1
export PATH=/usr/local/bin:/Applications/Postgres.app/Contents/MacOS/bin:$PATH

In order to run your Rails app locally, you need to create a Postgres user. The username is typically the name of you app, and is specified in your database.yml configuration file. The command is pretty self explanatory:

1
$ createuser [username]

Putting the pieces together

With everything installed, create the databases, start the Rails server and hope for the best:

1
2
3
4
5
$ cd ~/projects/myproject
$ bundle exec rake db:create
$ bundle exec rails server
=> Booting WEBrick
=> Rails 4.1.0 application starting in development on http://0.0.0.0:3000

The app should now show up at http://localhost:3000.

Note: If you want to save yourself from having to write bundle exec when executing gem binaries through Bundler, consider using binstubs: small wrapper scripts around gem binaries that delegate to the proper version of the gem. If you’re on Rails 4.1 or later, binstubs for rake and rails are already installed in the /bin folder. Otherwise, generate them using:

1
2
$ bundle binstubs rake
$ bundle binstubs rails

The correct versions of the binaries can now be invoked by:

1
2
$ bin/rake db:create
$ bin/rails server

To avoid having to type bin/, install rbenv-binstubs using Homebrew:

1
$ brew install rbenv-binstubs

You can now simply type:

1
2
$ rake db:create
$ rails server

Deploying your app to Heroku couldn’t be easier. Create an account and download the Heroku Toolbelt which gives you access to the heroku command. Use it to login and to create a new Heroku app. Creating a new app automatically sets up a git remote to which you can push your code in order to deploy.

1
2
3
4
5
6
7
$ cd ~/projects/myproject
$ git init
$ heroku login
$ heroku create
$ git add .
$ git commit -m "initial commit"
$ git push heroku master

That’s it! You now have a working local development environment and Heroku deployment all set up and ready to go.

Bonus material

Consider using Pow, a zero-config Rack server for OS X. Use it to serve your local apps. Install it as such:

1
$ curl get.pow.cx | sh

To set up an app, simply symlink it:

1
$ ln -s ~/projects/myproject ~/.pow/myproject

It will now be available locally at http://myproject.dev. You can even view it from your phones and tablets connected to your network by visiting http://myproject.[IP].xip.io, substituting [IP] with the IP of the computer running your app.

As you might have noticed, rbenv has a number of plugins available. I have already mentioned ruby-build for installing Ruby versions, rbenv-gem-rehash and rbenv-binstubs which lets you skip typing bundle exec over and over. Another really useful one is rbenv-vars which lets you set project specific environment variables.

Comments