Once installed, you’ll have access to the $ heroku command from your command shell. Log in using the email address and password you used when creating your Heroku account:

Note that $ symbol before commands indicates they should be run on the command line, prompt, or terminal with appropriate permissions. Do not copy the $ symbol.

$ heroku login
Enter your Heroku credentials.
Email: schneems@example.com
Password:
Could not find an existing public key.
Would you like to generate one? [Yn]
Generating new SSH public key.
Uploading ssh public key /Users/adam/.ssh/id_rsa.pub

Press enter at the prompt to upload your existing ssh key or create a new one, used for pushing code later on.

Write your App

To run on Heroku your app must be configured to use the Postgres database, have all dependencies declared in your Gemfile, and have the rails_12factor gem in the production group of your Gemfile

You may be starting from an existing app, if so upgrade to Rails 4 before continuing. If not, a vanilla Rails 4 app will serve as a suitable sample app. To build a new app make sure that you’re using the Rails 4.x using $ rails -v. You can get the new version of rails by running,

If you experience problems or get stuck with this tutorial, your questions may be answered in a later part of this document. Once you experience a problem try reading through the entire document and then going back to your issue. It can also be useful to review your previous steps to ensure they all executed correctly.

If already have an app that was created without specifying --database=postgresql you will need to add the pg gem to your Rails project. Edit your Gemfile and change this line:

gem 'sqlite3'

To this:

gem 'pg'

We highly recommend using PostgreSQL during development. Maintaining parity between your development and deployment environments prevents subtle bugs from being introduced because of differences between your environments. Install Postgres locally now if it is not allready on your system.

Be careful here, if you omit the sql at the end of postgresql in the adapter section your application will not work.

Welcome page

Rails 4 no longer has a static index page in production. When you’re using a new app, there will not be a root page in production, so we need to create one. We will first create a controller called welcome for our home page to live:

$ rails generate controller welcome

Next we’ll add an index page.

In file app/views/welcome/index.html.erb write:

<h2>Hello World</h2>
<p>
The time is now: <%= Time.now %>
</p>

Now we need to have Rails route to this action. We’ll edit config/routes.rb to set the index page to our new method:

Heroku gems

Heroku integration has previously relied on using the Rails plugin system, which has been removed from Rails 4. To enable features such as static asset serving and logging on Heroku please add rails_12factor gem to your Gemfile.

Specify Ruby version in app

Rails 4 requires Ruby 1.9.3 or above. Heroku has a recent version of Ruby installed by default, however you can specify an exact version by using the ruby DSL in your Gemfile. For this guide we’ll be using Ruby 2.

If you see fatal: not in a git directory then you are likely not in the correct directory. Otherwise you may deploy your code. After you deploy your code, you will need to migrate your database, make sure it is properly scaled and use logs to debug any issues that come up.

It is always a good idea to check to see if there are any warnings or errors in the output. If everything went well you can migrate your database.

Migrate your database

If you are using the database in your application you need to manually migrate the database by running:

$ heroku run rake db:migrate

Any commands after the heroku run will be executed on a Heroku dyno. You can obtain an interactive shell session by running $ heroku run bash.

Visit your application

You’ve deployed your code to Heroku. You can now instruct Heroku to execute a process type. Heroku does this by running the associated command in a dyno - a lightweight container which is the basic unit of composition on Heroku.

Let’s ensure we have one dyno running the web process type:

$ heroku ps:scale web=1

You can check the state of the app’s dynos. The heroku ps command lists the running dynos of your application:

You can also get the full stream of logs by running the logs command with the --tail flag option like this:

$ heroku logs --tail

Dyno sleeping and scaling

By default, your app is deployed on a free dyno. Free dynos will sleep after a half hour of inactivity and they can be active (receiving traffic) for no more than 18 hours a day before going to sleep. If a free dyno is sleeping, and it hasn’t exceeded the 18 hours, any web request will wake it. This causes a delay of a few seconds for the first request upon waking. Subsequent requests will perform normally.

$ heroku ps:scale web=1

To avoid dyno sleeping, you can upgrade to a hobby or professional dyno type as described in the Dyno Types article. For example, if you migrate your app to a professional dyno, you can easily scale it by running a command telling Heroku to execute a specific number of dynos, each running your web process type.

Console

Heroku allows you to run commands in a one-off dyno - scripts and applications that only need to be executed when needed - using the heroku run command. Use this to launch a Rails console process attached to your local terminal for experimenting in your app’s environment:

$ heroku run rails console
irb(main):001:0> puts 1+1
2

Rake

Rake can be run as an attached process exactly like the console:

$ heroku run rake db:migrate

Webserver

By default, your app’s web process runs rails server, which uses Webrick. This is fine for testing, but for production apps you’ll want to switch to a more robust webserver. On Cedar, we recommend Puma as the webserver. Regardless of the webserver you choose, production apps should always specify the webserver explicitly in the Procfile.

First, add Puma to your application Gemfile:

At the end of Gemfile add:

gem 'puma'

Then run

$ bundle install

Now you are ready to configure your app to use Puma. For this tutorial we will use the default settings of Puma, but we recommend generating a config/puma.rb file and reading more about configuring your application for maximum performance by reading the Puma documentation

Finally you will need to tell Heroku how to run your Rails app by creating a Procfile in the root of your application directory.

Procfile

Change the command used to launch your web process by creating a file called Procfile and entering this:

Set the RACK_ENV to development in your environment and a PORT to connect to. Before pushing to Heroku you’ll want to test with the RACK_ENV set to production since this is the enviroment your Heroku app will run in.

$ echo "RACK_ENV=development" >>.env
$ echo "PORT=3000" >> .env

You’ll also want to add .env to your .gitignore since this is for local enviroment setup.

The config.assets.initialize_on_precompile option has been removed is and not needed for Rails 4. Also, any failure in asset compilation will now cause the push to fail. For Rails 4 asset pipeline support see the Ruby Support page.

Troubleshooting

If you push up your app and it crashes (heroku ps shows state crashed), check your logs to find out what went wrong. Here are some common problems.

Runtime dependencies on development/test gems

If you’re missing a gem when you deploy, check your Bundler groups. Heroku builds your app without the development or test groups, and if your app depends on a gem from one of these groups to run, you should move it out of the group.

One common example using the RSpec tasks in your Rakefile. If you see this in your Heroku deploy: