If you don’t follow the Windows guide, note that you cannot run bundle install as you may need to install OpenSSL and the Puma web server manually.

First download OpenSSL. Next, extract the lzma download with 7Zip, and then extract the tar file to C:\openssl.

Verify the file is in the correct location:

$ dir c:\opensslbin include lib ssl

Now run:

$ gem install puma -- --with-opt-dir=c:\openssl

Once this finishes run:

$ bundle update puma

Set up

In this step you will install the Heroku Command Line Interface (CLI), formerly known as the Heroku Toolbelt. You will use the CLI to manage and scale your applications, to provision add-ons, to view the logs of your application as it runs on Heroku, as well as to help run your application locally.

Visit your application in the browser again, and you’ll see another log message generated.

Press Control+C to stop streaming the logs.

Define a Procfile

Use a Procfile, a text file in the root directory of your application, to explicitly declare what command should be executed to start your app.

The Procfile in the example app you deployed looks like this:

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

This declares a single process type, web, and the command needed to run it. The name web is important here. It declares that this process type will be attached to the HTTP routing stack of Heroku, and receive web traffic when deployed. The command used here is to run puma (the web server), passing in a configuration file.

Procfiles can contain additional process types. For example, you might declare one for a background worker process that processes items off of a queue.

Scale the app

Right now, your app is running on a single web dyno. Think of a dyno as a lightweight container that runs the command specified in the Procfile.

By default, your app is deployed on a free dyno. Free dynos will sleep after a half hour of inactivity (if they don’t receive any traffic). This causes a delay of a few seconds for the first request upon waking. Subsequent requests will perform normally. Free dynos also consume from a monthly, account-level quota of free dyno hours - as long as the quota is not exhausted, all free apps can continue to run.

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.

Scaling an application on Heroku is equivalent to changing the number of dynos that are running. Scale the number of web dynos to zero:

$ heroku ps:scale web=0

Access the app again by hitting refresh on the web tab, or heroku open to open it in a web tab. You will get an error message because you no longer have any web dynos available to serve requests.

Scale it up again:

$ heroku ps:scale web=1

For abuse prevention, scaling a non-free application to more than one dyno requires account verification.

Declare app dependencies

Heroku recognizes an app as a Ruby app by the existence of a Gemfile file in the root directory.

The demo app you deployed already has a Gemfile, and it looks something like this:

The Gemfile file specifies the dependencies that should be installed with your application. You can also use it to determine the version of Ruby that will be used to run your application on Heroku.

When an app is deployed, Heroku reads this file and installs the appropriate Ruby version together with the dependencies using the bundle install command.

A prerequisite to running any app locally is to install the dependencies locally as well. This particular Gemfile has a dependency pg which will only resolve if you have Postgres installed locally. Please install Postgres before you proceed.

Now run bundle install in your local directory to install the dependencies, preparing your system for running the app locally:

Once dependencies are installed, you will be ready to run your app locally.

Run the app locally

Running apps locally in your own dev environment does require some effort. Rails typically requires a database - and this sample application uses Postgres. Check out these instructions for a local install.

The Rails app also uses a database, so you’ll have to create the appropriate database and table using the rake task:

Almost every deploy to Heroku follows this same pattern. First, add the modified files to the local git repository:

$ git add .

Now commit the changes to the repository:

$ git commit -m "Demo"

Now deploy, just as you did previously:

$ git push heroku master

Finally, check that everything is working:

$ heroku open

Provision add-ons

Add-ons are third-party cloud services that provide out-of-the-box additional services for your application, from persistence through logging to monitoring and more.

By default, Heroku stores 1500 lines of logs from your application. However, it makes the full log stream available as a service - and several add-on providers have written logging services that provide things such as log persistence, search, and email and SMS alerts.

In this step you will provision one of these logging add-ons, Papertrail.

To help with abuse prevention, provisioning an add-on requires account verification. If your account has not been verified, you will be directed to visit the verification site.

The add-on is now deployed and configured for your application. You can list add-ons for your app like so:

$ heroku addons

To see this particular add-on in action, visit your application’s Heroku URL a few times. Each visit will generate more log messages, which should now get routed to the papertrail add-on. Visit the papertrail console to see the log messages:

$ heroku addons:open papertrail

Your browser will open up a Papertrail web console, showing the latest log events. The interface lets you search and set up alerts:

Start a console

You can run a command, typically scripts and applications that are part of your app, in a one-off dyno using the heroku run command. It can also be used to launch a REPL process attached to your local terminal for experimenting in your app’s environment:

To get a real feel for how dynos work, you can create another one-off dyno and run the bash command, which opens up a shell on that dyno. You can then execute commands there. Each dyno has its own ephemeral filespace, populated with your app and its dependencies - once the command completes (in this case, bash), the dyno is removed:

Define config vars

At runtime, config vars are exposed as environment variables to the application. For example, modify app/views/welcome/index.erb so that the method repeats an action depending on the value of the TIMES environment variable. Change the file so that its first few lines read as follows:

<% for i in 0..(ENV['TIMES'] ? ENV['TIMES'].to_i : 2) do %><p>Hello World #<%= i %>!</p><% end %>

heroku local will automatically set up the environment based on the contents of the .env file in your local directory. In the top-level directory of your project there is already a .env file that has the following contents:

TIMES=10

If you run the app with heroku local, you’ll see “Hello World” ten times.

Use a database

The add-on marketplace has a large number of data stores, from Redis and MongoDB providers, to Postgres and MySQL. In this step you will learn about the free Heroku Postgres add-on that is provisioned automatically on all Rails app deploys.

A database is an add-on, and so you can find out a little more about the database provisioned for your app using the addons command in the CLI:

This indicates I have a hobby database (free), running Postgres 9.3.3, with a single row of data.

The example app you deployed already has database functionality - it has a controller and database model for widgets - which you should be able to reach by visiting your app’s URL and appending ’/widgets’.

If you do visit the URL, you’ll see an error page appear. Check out the error message in using heroku logs or in Papertrail, and you’ll see something like this:

This indicates that while we could connect to the database, the necessary table wasn’t found. In Rails, you can fix that by running rake db:migrate. To execute this command on Heroku, run it in a one-off dyno like so:

Just like your web process type runs in a dyno, so too did this rake command. Heroku effectively boots a new dyno, adds in your prepared app, and then executes the command in that context - and afterwards removes the dyno. As the dyno performs its actions on a connected add-on, that’s just perfect.

Now if you visit the /widgets page of your app again, you’ll be able to list and create Widget records.

You can also interact directly with the database if you have Postgres installed locally. For example, here’s how to connect to the database using psql and execute a query: