Last updated June 05, 2018

This article covers how to run a Ruby on Rails application on Heroku. It assumes a knowledge of both Heroku and with Rails. If you are new to either please see the Getting Started with Rails 4.x on Heroku instead. This article assumes that you have a copy of the Heroku CLI installed locally.

Most of Rails works out of the box with Heroku, however there are a few things you can do to get the most out of the platform. To do this you will need to configure your Rails 4 app to connect to Postgres, your logs need to be configured to point to STDOUT, and your application needs to have serving assets enabled in production.

Logging and assets

Heroku treats logs as streams and requires your logs to be sent to STDOUT. To enable STDOUT logging in Rails 4 you can add the rails_12factor gem. This gem will also configure your app to serve assets in production. To add this gem add this to your Gemfile:

gem 'rails_12factor', group: :production

This gem allows you to bring your application closer to being a 12factor application. You can get more information about how the gem configures logging and assets read the rails_12factor README. If this gem is not present in your application, you will receive a warning while deploying, and your assets and logs will not be functional.

Postgres

Your application needs to be configured to use the Postgres database. Newly generated Rails 4 applications are configured to use sqlite. To use Postgres instead add the pg gem to your Gemfile:

gem 'pg'

We recommend using the same database in development and production to maintain dev/prod parity. You will need to remove the sqlite gem from your gemfile or place it in a non production group. You can read more about why you should not run sqlite on Heroku, which also contains detailed instructions on setting up Postgres locally.

Ruby version

Rails 4 Requires a Ruby version of 1.9.3 or higher. Heroku has a ruby version installed by default for all new applications, so you don’t need to do anything here. However, we recommend setting your Ruby version in your Gemfile.

When you declare your Ruby version, you get parity between production, and between developers.

Upgrading a Rails 3 app

If you are upgrading an application from Rails 3 you will need to first get your application working with Rails 4 locally. We recommend following this guide for upgrading to Rails 4. Once complete, follow the previous instructions. Then you need to run a command to generate a bin directory in your project. In the root directory of an app upgraded to Rails 4 run:

$ rake rails:update:bin

This will generate a bin directory in the root of your application. Make sure that it is not in your .gitignore file, and check this directory and its contents into git. We recommend making large changes in feature branches and testing regularly using staging servers. You can make a new staging server by forking an existing application to create a staging application if you do not have a staging server.

Deploying

Deploying a Rails 4 application is identical to deploying an Rails 3 application. Make sure all of your files are in git:

$ git add .
$ git commit -m 'deploying rails 4'

Then create a new Heroku app by running $ heroku create, or push to an existing one by running:

$ git push heroku master

If the deploy fails check the build output for warnings and errors. If it succeeds, but your site does not load correctly, check the logs:

$ heroku logs --tail

Running

A Rails 4 application will be run the same way as a Rails 3 application. You can manually define how to start your web process by creating a Procfile in the root of your directory:

web: bundle exec puma -C config/puma.rb

The PORT will be assigned to each of your dynos separately through the PORT environment variable. Heroku recomends running your Rails 4 app on a concurrent webserver such as Puma. If you do not specify a Procfile, Heroku will run your application using webrick through the $ rails server command. While webrick is available through the standard library, we do not recommend using in production. To get the best performance and most consistent experience we recommend you specify how to run your web service in your Procfile.