rails heroku tutorial
Last updated 10 May 2012
Here’s how to set up an app with Rails 3.2 and Ruby 1.9.3 on Heroku. Heroku provides low cost, easily configured Rails 3.2 application hosting. See a discussion on Quora What are the potential downsides of using Heroku? (not many).
Update! Heroku now officially gives you a choice of Ruby versions, including 1.9.3. See Multiple Ruby Version Support on Heroku.
See Installing Rails 3.2 for advice and suggestions on setting up the newest version of Rails on your own computer.
This is a guide for developers using the starter apps from the Rails Apps repository. Others may find it helpful as well.
See a list of recommended resources for Rails.
Add the Heroku gem to your application’s Gemfile (check rubygems.org for the latest heroku gem):
gem "heroku"
Install your gems with:
$ bundle install
If you haven’t done so, add your public key after installing the heroku gem so that you can use git to push or clone Heroku app repositories. For more information, see Heroku’s documentation Managing Your SSH Keys.
As an alternative to installing the Heroku gem, Heroku offers a stand-alone “Heroku Toolbelt” which installs the Heroku command-line client and the Git revision control system. You can use either the Heroku gem or the Heroku Toolbelt. For more information, see Heroku’s documentation Installing the Heroku CLI.
To deploy an app to Heroku, you must have a Heroku account. Visit http://heroku.com/ to set up an account.
You may want to deploy an app to an account that belongs to someone other than yourself (for example, your employer or a client). If you are using a client’s or employer’s Heroku account, you won’t be able to push your application to Heroku until you’ve added yourself as a collaborator. After you create an app on Heroku, log in to your client’s account on Heroku. Under “My Apps” you’ll see the name of the app you’ve created; click “General Info” and you’ll find a form where you can add yourself as a collaborator.
David Dollar’s heroku-accounts plugin will help if you must use multiple accounts on Heroku. With the heroku-accounts plugin, you can configure each application to deploy to the appropriate account.
To install the heroku-accounts plugin:
heroku plugins:install git://github.com/ddollar/heroku-accounts.git
To add an account locally (which you’ll call “work”):
$ heroku accounts:add work --auto
To list accounts that are set up locally:
$ heroku accounts
To set an account to use for a project:
# in project root heroku accounts:set work
Heroku uses PostgreSQL as its default database. Heroku does not support SQLite or MySQL, the databases most commonly used for local development.
As a general practice, you should use the same environment for local development as you do for production, which means using the same database systems locally and in production. In practice, with ActiveRecord isolating the database system, this may not be critically important.
If you don’t want to develop using PostgreSQL locally, you can set up your Gemfile to use SQLite for development and PostgreSQL for production. To switch from SQLite to PostgreSQL for deployment to Heroku, edit your Gemfile and change this line:
gem 'sqlite3'
To this:
group :development, :test do gem 'sqlite3' end group :production do gem 'pg' end
Run bundle install --without production to update your gems. The flag --without production allows you to skip local installation of the pg gem; otherwise, you will have to install PostgreSQL locally (the pg gem won’t install if PostgreSQL is not installed).
If you’d like to use PostgreSQL both locally and on Heroku for production, edit your Gemfile and change this line:
gem 'sqlite3'
To this:
gem 'pg'
You’ll have to install PostgreSQL locally before running bundle install.
I recommend considering MongoDB as an alternative. It simplifies development by eliminating the schemas and migrations required by SQLite, MySQL, or PostgreSQL. The MongoHQ add-on is offered by Heroku and provides a hosted MongoDB datastore.
If you decide to try MongoDB, take a look at the example apps (with detailed tutorials) that combine Mongoid with Devise or Mongoid with OmniAuth.
By default, the file config/mongoid.yml contains this:
# set these environment variables on your prod server production: host: <%= ENV['MONGOID_HOST'] %> port: <%= ENV['MONGOID_PORT'] %> username: <%= ENV['MONGOID_USERNAME'] %> password: <%= ENV['MONGOID_PASSWORD'] %> database: <%= ENV['MONGOID_DATABASE'] %>
To use MongoDB with your app, modify the file config/mongoid.yml to look like this:
# set these environment variables on your prod server production: uri: <%= ENV['MONGOHQ_URL'] %>
By default, when you run rails server locally, Rails launches the simple Webrick web server. For production apps Heroku recommends using a more robust webserver such as Thin.
To use Thin, add the gem to your Gemfile:
gem 'thin'
If you want to continue to use Webrick as your local web server, with Thin on Heroku, set up your Gemfile like this:
group :production do gem 'thin' end
Run bundle install --without production to update your gems.
Heroku recommends adding a Procfile to your app. Procfile is a mechanism for declaring what commands are run when your web app runs on the Heroku platform. A Procfile is not necessary to deploy a Rails app to Heroku, but Heroku recommends it for greater control and flexibility over your app. If you add a Procfile, you can specify Thin as your web process in the Procfile.
For simplicity, there’s no need to create a Procfile if you use Thin. If you declare the Thin gem in your Gemfile, Heroku sets up an appropriate web process without requiring a Procfile.
Your application must be committed to a Git repository before you can use Heroku. See Using Git with Rails to learn how to set up Git for your application.
Store the modified application in the Git repository:
$ git commit -am "Configured for deployment to Heroku"
Use the Heroku create command to create and name your new app.
$ heroku create myapp --stack cedar
Heroku demands a unique name for every hosted application. Replace “myapp” with something unique. If it is not unique, you’ll see an error, “name is already taken.”
You can check that everything has been added correctly by running:
$ heroku info --app myapp
Heroku’s newest stack, “Celadon Cedar,” supports Rails 3.2 but installs Ruby 1.9.2 by default. Ruby 1.9.3 is recommended for Rails 3.2.
You can configure the Heroku environment to use Ruby 1.9.3.
Note: Heroku makes it clear that Ruby 1.9.3 on Heroku is experimental, which means “no support, the ruby_version will change in the future, and this feature may change or be removed without warning.” In response to an inquiry on January 31, 2012, Heroku said, “there is no timeline yet” to fully support Ruby 1.9.3.
Note: Installing Ruby 1.9.3 on Heroku previously (before March 19, 2012) required installation of the heroku-labs plugin. The heroku-labs plugin is deprecated and its functionality is now incorporated in the heroku client gem.
Enable the “user_env_compile” feature (see Heroku’s documentation):
$ heroku labs:enable user_env_compile -a myapp
Set the RUBY_VERSION variable:
$ heroku config:add RUBY_VERSION=ruby-1.9.3-p125
Set the Heroku PATH config variable to include “bin”:
$ heroku config:add PATH=bin:vendor/bundle/ruby/1.9.1/bin:/usr/local/bin:/usr/bin:/bin
(Yes, the library path includes “1.9.1”: that’s not a typo.)
You can check that everything has been configured correctly by running:
$ heroku config
Heroku has no specific documentation for Rails 3.2 but the following articles on Rails 3.0 and Rails 3.1 are helpful:
Note: Prior to Rails 3.1.0.rc5, Heroku required an additional gem therubyracer-heroku. This gem is no longer needed for Rails 3.2 and should not be used.
If you are using MongoDB, you can use a Heroku add-on to deploy your app using the MongoHQ service. See details about the service and details about installation.
To use MongoDB with your app, enable the add-on with the following command:
$ heroku addons:add mongohq:free
If you deploy your app and get the error message “failed to connect to any given host:port” or “Failed to connect to a master node at localhost:27017”, the config/mongoid.yml file may not have the correct MongoHQ connection parameters.
The file config/mongoid.yml should look like this:
# set these environment variables on your prod server production: uri: <%= ENV['MONGOHQ_URL'] %>
Push your application to Heroku:
$ git push heroku master
Note: If you are using a client’s or employer’s Heroku account, you won’t be able to push your application to Heroku until you’ve added yourself as a collaborator. After you create the app on Heroku, log in to your client’s account on Heroku. Under “My Apps” you’ll see the name of the app you’ve created; click “General Info” and you’ll find a form where you can add yourself as a collaborator.
You’ll need to run your database migrations (not applicable if you are using MongoDB):
$ heroku run rake db:migrate
Initialize your application database if your application requires it:
$ heroku run rake db:seed
These two commands can be combined as:
$ heroku run rake db:setup
Heroku doesn’t support rake db:reset.
Need to reset your Heroku PostgreSQL database? Here’s how:
$ heroku pg:reset SHARED_DATABASE --confirm myapp
Don’t forget to restart your application or you won’t see any changes:
$ heroku restart
Open your Heroku site in your default web browser:
$ heroku open
Your app will be running at http://my-app-name.herokuapp.com/.
Unless you enable email on Heroku, you’ll get errors when your application tries to send email from Heroku.
Heroku offers several options for sending email from your Rails application. See Heroku’s documentation Sending Email from Your App.
If you’re sending test emails during development, Gmail is the easiest option.
To use Gmail from Heroku, add the following to your config/environments/production.rb file:
config.action_mailer.default_url_options = { :host => 'myapp.heroku.com' }
config.action_mailer.delivery_method = :smtp
config.action_mailer.perform_deliveries = true
config.action_mailer.raise_delivery_errors = false
config.action_mailer.default :charset => "utf-8"
config.action_mailer.smtp_settings = {
address: "smtp.gmail.com",
port: 587,
domain: "myapp.heroku.com",
authentication: "plain",
enable_starttls_auto: true,
user_name: ENV["GMAIL_USERNAME"],
password: ENV["GMAIL_PASSWORD"]
}
To avoid storing your Gmail username and password in your Git repository, use environment variables to pass the username and password to your application. See Heroku’s documentation Configuration and Config Vars.
Set your Gmail username and password as Heroku environment variables:
$ heroku config:add GMAIL_USERNAME=no-reply@example.com GMAIL_PASSWORD=please
You’ll likely want to use your own domain name for your app. The easiest way to set up your own domain with Heroku is to use the Zerigo DNS add-on. See Heroku’s article about setting up Zerigo DNS and Heroku’s article about custom domains for more information.
Visit your domain registrar and set your domain’s nameserver records to point to Zerigo’s DNS servers:
a.ns.zerigo.net b.ns.zerigo.net c.ns.zerigo.net d.ns.zerigo.net e.ns.zerigo.net
Use the command line to enable Heroku to use a custom domain for your app:
$ heroku addons:add custom_domains:basic
Use the command line to enable the Zerigo DNS add-on:
$ heroku addons:add zerigo_dns:basic
With the Zerigo DNS add-on enabled, domain names added via the command line will automatically be added to Zerigo’s DNS servers. Updates happen instantly and Heroku keeps the DNS records up-to-date should Heroku change the IP addresses of its servers.
This command tells Heroku that your app should respond to requests to “mydomain.com”:
$ heroku domains:add mydomain.com
As soon as DNS records propagate (usually a few minutes but sometimes longer), your app should be running at http://mydomain.com/.
You’ll need to enable “wildcard domains” if you want your application to accommodate arbitrary subdomains (for example, a different subdomain for each user account),
$ heroku addons:add wildcard_domains
$ heroku domains:add *.mydomain.com
You can check that everything has been added correctly by running:
$ heroku info --app myapp
When you get errors, troubleshoot by reviewing the log files:
$ heroku logs
Your best source for help with Heroku is Stack Overflow. Your issue may have been encountered and addressed by others.
You can also check the Heroku Dev Center or the Heroku Google Group.