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:
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:
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:
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:
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
Add rbenv init to your .bash_profile to enable both shims and autocompletion:
Install the version(s) of Ruby that you need for your projects using the
install command that is added by ruby-build:
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
If you want something other than the bundled OS X Ruby version available throughout your system, setting a global version is a good idea:
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
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:
Let’s set up a Rails app:
Rails has now created a Gemfile, which is a list of project dependencies to be installed by Bundler. Install them:
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:
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:
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:
Putting the pieces together
With everything installed, create the databases, start the Rails server and hope for the best:
1 2 3 4 5
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:
The correct versions of the binaries can now be invoked by:
To avoid having to type
bin/, install rbenv-binstubs using Homebrew:
You can now simply type:
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
That’s it! You now have a working local development environment and Heroku deployment all set up and ready to go.
Consider using Pow, a zero-config Rack server for OS X. Use it to serve your local apps. Install it as such:
To set up an app, simply symlink it:
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.