From Start to Finish: Install Ruby on Rails on Mac, Deploy on Heroku

John John (304)
20 minutes

Ruby on Rails is one of the most popular web development frameworks, and Heroku has become a popular place to quickly deploy applications - and both for very good reason. For this guide, you will need a Heroku account (it's free to sign up).

Heroku Account×1
Ruby 2.0×1
Rails 4.2×1

Howchoo is reader-supported. As an Amazon Associate, we may earn a small affiliate commission at no cost to you when you buy through our links.

If Xcode is already installed, you can skip this step. To check, open your Terminal application and type:

xcode-select -p

If Xcode is installed you will see the path in the Applications directory:


If it's not installed type:

xcode-select --install

and you will be prompted to install the Xcode Command Line Tools.

After installing, verify the install:

$ xcode-select -p

and finally ensure gcc is installed:

$ gcc --version
Configured with: --prefix=/Applications/ --with-gxx-include-dir=/usr/include/c++/4.2.1
Apple LLVM version 5.0 (clang-500.2.79) (based on LLVM 3.3svn)
Target: x86_64-apple-darwin14.1.0
Thread model: posix

Git is a popular version control software, and it will be required to push to Heroku in later steps. If you've successfully installed Xcode, git will be installed as well. You can go ahead and configure git now.

First, you can confirm that git is installed:

$ git --version
git version (Apple Git-47)

and now configure it by typing:

$ git config --global "Your Real Name"
$ git config --global
$ git config -l --global Real Name

The above commands will set your name and your email address. Then the third line simply checks to make sure they were set properly. These values will be used to identify your commits.

Homebrew is a popular package manager for OSX. There are other great package managers, but for this guide we will use homebrew.

To install, type:

$ ruby -e "$(curl -fsSL"

RVM is the ruby version manager. This allows you to have multiple ruby environments on the same machine. You may not need multiple environments, but it's the easiest way to setup the environment you need for this guide.

To install, type:

\curl -L | bash -s stable --ruby

The --ruby flag installs the latest version of ruby.

RubyGems should be installed, but you can check the version with this:

$ gem -v

and update if necessary:

$ gem update --system

To check which gems are installed in the global gemset, use:

$ rvm gemset use global
$ gem list

This will list your gems, and if you'd like you can update any stale gems:

gem update

I also recommend using the following the speed up gem installation by disabling documentation:

$ echo "gem: --no-document" >> ~/.gemrc

Lastly, we should install Nokogiri in the global gemset. Many gems, including rails, depend on Nokogiri.

$ gem install nokogiri

For this guide, we will create a new gemset to install for this specific version of rails. You could skip this command and by default you would be installing rails in the global gemset.

To make a gemset for the current stable release type:

$ rvm use ruby-2.2.0@rails4.2 --create

At the time of this writing, rails 4.2 is the current version. If a new version is out you can name the gemset it appropriately.

Use the following to install the latest version of rails:

$ gem install rails

After it finishes installing, check that rails is installed:

$ rails -v

I typically keep all of my development projects in ~/Developer, but you can organize your projects however you'd like.

To follow my example, let's create the Developer folder as well as our specific project folder:

$ mkdir -p ~/Developer/my_rails_project

At this point, we're going to switch gears. You could skip straight to creating your rails app and worry about this step later if you'd like, but I think this is the most logical point to get your heroku environment setup.

As mentioned in the guide description, you'll need to set up an account on Heroku. It's free to sign up, so go ahead and do that if you haven't already. Make sure to remember your login information.

Install the Heroku Toolbelt. This gives you access to the Heroku command line tools, which allow you to deployment your project files to your Heroku environment which we will do in subsequent steps.

With the Heroku Toolbelt installed, go ahead and log in to Heroku in your console. To do this type:

$ heroku login

You will be prompted to enter your email address and password.

Heroku requires postgres so we will use postgress in our development environment as well. We'll install using homebrew, like this:

$ brew install postgres

Then run this command to finish installing the database:

$ initdb /usr/local/var/postgres

Run the following commands to start postgres upon login:

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

Now, you can install the postgres gem that will be required for your rails application:

$ gem install pg

If you followed my example for setting up your project folders you can cd into your project folder like this:

cd ~/Developer/my_rails_project

From within your project folder, you can create your rails app like this:

rails new . --database=postgresql

Next, we should make sure all necessary gems are installed. The following command will check and install all gems in your Gemfile. So if you install a gem on your local environment, you need to add it to your Gemfile as well. While developing, you'll find that many bugs can be fixed by either making sure your Gemfile is up to date or simply running the following command:

$ bundle install

Rails makes this part easy. Once you've got your rails app created simply run the following two commands from the command line:

$ rake db:create:all
$ rake db:migrate
Now let's test our local environment

We should be setup and ready to start developing, but first let's test our local environment. From your project root, run:

$ rails server

This will create a local webserver running your rails application. To visit see your app, go to http://localhost:3000 in a web browser.

You should see the Rails welcome page.

Now that we've got a working - although quite boring - rails application, we can go ahead and push our code to Heroku. You might decide in the future to build out your application a little more before deploying, but for this guide we will just deploy our bare application so you can get familiar with the process.

First we'll want to initialize this application in git.

$ git init
$ git add .
$ git commit -m "init"

This initializes, adds all of the code, and creates your first commit message.

Now we'll create our heroku application. This can also be done from the Heroku website, but we'll do it here for simplicity.

$ heroku create

Now verify that the remote app was created:

$ git config --list | grep heroku

Now we can deploy our code:

$ git push heroku master
Test our heroku environment

We'll want to view our application on Heroku, even if it doesn't do anything interesting.

So first we'll make sure we have one dyno running the web process:

$ heroku ps:scale web=1

And double check that the process is running:

$ heroku ps
=== web (1X): `bin/rails server -p $PORT -e $RAILS_ENV`
web.1: up 2015/02/23 09:06:08 (~ 1m ago)

Now, let's check out our application in the browser!

$ heroku open

This will open up a new browser tab to view your application on heroku. Since this is the production environment, we won't get any error messages or the rails test page. It will simply 404 since we haven't set up any routes or controllers. But at least we know it's working.

Now you can start writing your rails application and future deployments can be achieved through the command we used initially:

$ git push heroku master

If you found any issues with this guide, please report them. I'm hoping this can serve as a great guide for beginners and a reference for more experienced developers:

Browser lagging? Clear your cache!
Ash Ash (362)

Clearing your cookies and cache is a useful way to solve minor latency issues and other small problems when using a web browser. On every new Android phone, the default browser is Chrome.