Small Topics

Earlier you learned how to deploy your app to the Heroku platform. In this section you’ll learn how to work with various Heroku features and add-ons.

Core Features

Setting Configuration Variables

As your app grows it will need various pieces of configuration data to run. Some of this data will be too sensitive or change too frequently for you to be able to store it in source control. Heroku allows you to store configuration variables so that your app can configure itself in production mode.

All apps start out with a default set of variables, which you can view with the command heroku config. Pay special attention to RACK_ENV (which determines the environment your app boots into) and DATABASE_URL which points at your app’s database.

Read more about Heroku configuration variables.

Setting Up Workers

For performance reasons, most web applications end up offloading work to worker processes that operate asynchronously, outside the context of a web request. This usually involves setting up a queueing system such as delayed_job or Resque.

delayed_job is the more documented, simpler approach since you can use your existing relational database. Follow Heroku’s setup instructions to get this running.

Note that if you are creating an app using Heroku’s Cedar stack, you will need to add a worker process to the app’s Procfile, described below.

Using the Procfile

Heroku’s Celadon Cedar stack affords much more flexibility about what kinds of processes can be run on Heroku. A typical web app configuration using delayed_job and thin is below:

1
2

worker: bundle exec rake jobs:work
web: bundle exec thin start -p $PORT -e $RACK_ENV

Read more about Procfile configuration here.

Scaling Dynos

As your app gets more usage you will need more processes (called dynos) to handle requests.

Use the ps:scale command to increase thenumber of dynos allocated to each of the processes in your Procfile. You can specify absolute numbers like 2 for 2 total dynos, or relative numbers like +1, for one additional dyno:

$

heroku ps:scale web=2 worker+1

The names "web" and "worker" in this case refer to the labels in your Procfile.

Configuring the Rails 3.1 Asset Pipeline

If your app uses the Rails asset pipeline, Heroku will compile the assets for you at deploy time using the rake assets:precompile task. Be sure to add these gems to the asset group in your Gemfile:

Managing Data

Exporting Data

The simplest way to export your database is the pgbackups:url command to get a temporarily-accessible download:

$

curl -o latest.dump `heroku pgbackups:url`

You can also transfer data between Heroku databases using the procedure explained at the end of the pgbackups documentation.

Importing Data

The pgbackups:restore command will pull data from a URL into your database like so:

$

heroku pgbackups:restore DATABASE 'http://example.com/location/of/your/dump'

Automating Database Backups

The PG Backups add-on will perform automatic daily backups, retaining the last 7 daily backups and 5 weekly backups. Add this to your app via:

$

heroku addons:add pgbackups:auto-month

If you know you’re about to try something sensitive, you can perform manual backups. Heroku will retain 10 of them with the default plan. Create an immediate backup using this command:

$

heroku pgbackups:capture

Read more about Heroku backups.

Using a Dedicated Database

Heroku apps start off using a shared database. The performance of a shared database is only acceptable for staging environments or "low-scale production applications". Once you start to see serious usage you’ll want to switch to a dedicated database. This upgrade can only be done from Heroku’s web U/I since a significant cost increase is involved.

Add-Ons

Setting Up Custom Domains

You can run your app for free at a custom domain name by running:

$

heroku addons:add custom_domains:basic

Add the domain names like this:

$
$

heroku domains:add www.example.comheroku domains:add example.com

You must configure a CNAME for your domains to point to Heroku in order for this to work, as explained in detail in the Heroku Custom Domains documentation.

Using Cron

Heroku will run short-duration daily and hourly batch jobs for you using the Cron add-on.

You need to add a rake task named "cron" to your app in lib/tasks/cron.rake.

1
2
3
4
5
6
7
8
9
10

desc "run cron jobs"
task cron: :environment do
  if Time.now.hour % 3 == 0
    puts "do something every three hours"
  end

  if Time.now.hour == 0
    puts "do something at midnight"
  end
end

With this task in place, just setup the add-on:

 
$
 
 
$

# daily cron is freeheroku addons:add cron:daily# hourly cron costs $3/monthheroku addons:add cron:hourly

Setting Up SSL

If your app requires SSL your best option is to use Heroku’s Hostname Based SSL.

Heroku offers other options but that one works for most cases, and is among the easiest to setup. You’ll need to purchase an SSL certificate for your domain. Follow the direction on Heroku’s SSL documentation in order to add the certificate to your account.

If your SSL certificate requires the use of an intermediate certificate, be sure to append that file to your .pem file as described in the Heroku SSL documentation.

Once the certificate is added, the SSL add-on can be activated like this:

$

heroku addons:add ssl:hostname

You will receive an email from Heroku containing the hostname of your SSL endpoint. You will need to add a CNAME to your domain’s DNS settings corresponding to this endpoint.

Automating Deployment with Kumade

Although Heroku deployment is as simple as typing git push heroku, over time you may want more control over the deployment process. Or you may wish to automate other tasks like running migrations, packaging assets, and preventing deployments when your git repository is not clean.

Thoughtbot has created a gem called kumade which handles this for you. With it installed, instead of git push heroku you deploy with bundle exec kumade.

Sending Email with Sendgrid

The Sendgrid add-on gives you the ability to send outbound email from your app, saving you from needing to run your own SMTP server. The free version lets you send 200 emails per day.

Add Sendgrid using this command:

$

heroku addons:add sendgrid:free

The Sendgrid documentation explains how to configure ActionMailer to use Sendgrid’s SMTP servers, which should be done in your config/environments/production.rb file:

1
2
3
4
5
6
7
8

config.action_mailer.smtp_settings = {
  address:        "smtp.sendgrid.net",
  port:           "25",
  authentication: :plain,
  user_name:      ENV['SENDGRID_USERNAME'],
  password:       ENV['SENDGRID_PASSWORD'],
  domain:         ENV['SENDGRID_DOMAIN']
}