Find file
Fetching contributors…
Cannot retrieve contributors at this time
381 lines (370 sloc) 28.8 KB
<!DOCTYPE html>
<meta http-equiv="Content-Type" content="text/html; charset=utf-8"/>
<title>Rails Heroku Tutorial &#183; RailsApps</title>
<link href="" rel="publisher" />
<link rel="stylesheet" href="" type="text/css" charset="utf-8" />
<link rel="stylesheet" href="" type="text/css" charset="utf-8" />
<link rel="stylesheet" href="" type="text/css" charset="utf-8" />
<link rel="stylesheet" href="" type="text/css" charset="utf-8" />
<link rel="stylesheet" href="" type="text/css" charset="utf-8" />
<script src="" type="text/javascript"></script>
<script src="" type="text/javascript"></script>
<script src="" type="text/javascript"></script>
<script src="" type="text/javascript"></script>
<script src="" type="text/javascript"></script>
<script type="text/javascript">
var _gaq = _gaq || [];
_gaq.push(['_setAccount', 'UA-5109366-14']);
(function() {
var ga = document.createElement('script'); ga.type = 'text/javascript'; ga.async = true;
ga.src = ('https:' == document.location.protocol ? 'https://ssl' : 'http://www') + '';
var s = document.getElementsByTagName('script')[0]; s.parentNode.insertBefore(ga, s);
<div class="navbar navbar-fixed-top">
<div class="navbar-inner">
<div class="container">
<a href="" class="brand">RailsApps Project</a>
<ul class="pull-right nav">
<li><a href="" class="twitter">Blog</a></li>
<li><a href="" class="twitter">Twitter</a></li>
<li><a href="" class="google">Google +</a></li>
<li><a href="" class="github">GitHub Repository</a></li>
<div class="container">
<div class="content wikistyle gollum textile">
<h1>Rails Heroku Tutorial</h1>
<h4>by Daniel Kehoe</h4>
<p><em>Last updated 18 July 2012</em></p>
<p>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.</p>
<p>An article, <a href="">Heroku Isn’t for Idiots</a>, describes why you might want to use Heroku. And a discussion on Quora explains, <a href="">What are the potential downsides of using Heroku?</a> (not many).</p>
<h3>RailsApps Examples and Tutorials</h3>
<p>This is a guide for developers using the example apps from the RailsApps repository. The RailsApps project provides open source apps and detailed tutorials for Rails developers. You may already have built an app that’s ready to deploy on Heroku; next time you build an app, check the <a href="">RailsApps</a> project to see if we can save you some time with a starter app.</p>
<p><a href=""><img src="" title="Follow on Twitter" alt="Follow on Twitter"></a> Follow <a href="">@rails_apps</a> on Twitter for updates and timely Rails tips.</p>
<h2>Before You Start</h2>
<p>To deploy an app to Heroku, you must have a Heroku account. Visit <a href=""></a> to set up an account. Or you can use someone else’s account (such as a client’s or employer’s if you have login credentials); see details below.</p>
<p>Before you start, you should review the advice offered in the article <a href="">Installing Rails</a> to be sure your development environment is set up correctly on your local machine.</p>
<h2>Ruby 1.9.3 on Heroku</h2>
<p>Heroku’s newest stack, “Celadon Cedar,” supports Ruby 1.9.3 and Rails 3.2. As of 9 May 2012, Heroku officially supports Ruby 1.9.3 (see <a href="">Multiple Ruby Version Support on Heroku</a>).</p>
<p>You configure the Heroku environment to use Ruby 1.9.3 by specifying the Ruby version in your application Gemfile. This requires use of the newest version of the <a href="">Bundler</a> gem. You must install Bundler 1.1.5 or newer if you plan to deploy to Heroku (see instructions below).</p>
<p>You cannot specify a patch level for a Ruby version (such as ruby-1.9.3-p194). Heroku provides the most secure patch level of whatever minor version number you request.</p>
<p><em>Note:</em> You may have found outdated instructions elsewhere. To clarify: 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. Before May 9, 2012, installing Ruby 1.9.3 on Heroku required the <a href="">user_env_compile</a> feature; this is now deprecated. Furthermore, it is no longer necessary to set the RUBY_VERSION variable with <code>$ heroku config:add RUBY_VERSION=ruby-1.9.3-p125</code> or to set the Heroku <span class="caps">PATH</span> config variable to include “bin” when you specify the default Ruby 1.9.3 for the Cedar stack. Prior to Rails 3.1.0.rc5, Heroku required an additional gem <code>therubyracer-heroku</code>. This gem is no longer needed for Rails 3.2 and should not be used.</p>
<p>The following Heroku articles on Rails 3.1 are helpful:</p>
<li><a href="">Heroku Ruby Support</a></li>
<li><a href="">Getting Started with Rails 3.x on Heroku/Cedar</a></li>
<li><a href="">Rails 3.1+ Asset Pipeline on Heroku Cedar.</a></li>
</ul><h3>Updating Bundler for Heroku</h3>
<p>These instructions assume you are using rvm, the <a href="">Ruby Version Manager</a>. Bundler and rubygems-bundler are installed in rvm’s “global” gemset.</p>
<p>First, update to the <a href="">newest version of Rubygems-Bundler</a>.</p>
$ rvm gemset use global
$ gem update rubygems-bundler
$ gem list
<p>Then install Bundler version 1.1.5 (or newer).</p>
$ rvm gemset use global
$ gem update bundler
$ bundle --version
<p>If you encounter any issues when updating rubygems-bundler and Bundler, review the detailed instructions in the article <a href="">Installing Rails</a>.</p>
<p>Switch back to your application-specific gemset to proceed:</p>
$ rvm gemset use &lt;whatever&gt;
<h2>Preparing a Gemfile for Heroku</h2>
<p>You’ll add the Heroku gem and specify a Ruby version in your application’s gemfile.</p>
<h3>Specifying a Ruby Version</h3>
<p>Specify a Ruby version before specifying any gems:</p>
source ''
ruby '1.9.3'
gem 'rails', '3.2.6'
<h3>Heroku Gem</h3>
<p>Add the Heroku gem to your application’s Gemfile <a href="">(check for the latest heroku gem)</a>:</p>
<p><code>gem "heroku"</code></p>
<p>Install your gems with:</p>
<p><code>$ bundle install</code></p>
<p>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 <a href="">Managing Your <span class="caps">SSH</span> Keys</a>.</p>
<p><em>Note:</em> 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 <a href="">Installing the Heroku <span class="caps">CLI</span></a>. It’s probably easier to simply use the Heroku gem.</p>
<h2>Database Configuration</h2>
<p>Heroku uses PostgreSQL as its default database. Heroku does not support SQLite or MySQL, the databases most commonly used for local development.</p>
<h3>Use SQLite Locally and PostgreSQL on Heroku</h3>
<p>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.</p>
<p>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:</p>
<p><code>gem 'sqlite3'</code></p>
<p>To this:</p>
group :development, :test do
gem 'sqlite3'
group :production do
gem 'pg'
<p>Run <code>bundle install --without production</code> to update your gems. The flag <code>--without production</code> 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).</p>
<h3>Use PostgreSQL Locally and on Heroku</h3>
<p>If you’d like to use PostgreSQL both locally and on Heroku for production, edit your Gemfile and change this line:</p>
<p><code>gem 'sqlite3'</code></p>
<p>To this:</p>
<p><code>gem 'pg'</code></p>
<p>You’ll have to install PostgreSQL locally before running <code>bundle install</code>.</p>
<h3>The MongoDB Alternative</h3>
<p>MongoDB simplifies development by eliminating the schemas and migrations required by SQLite, MySQL, or PostgreSQL. The <a href="">MongoHQ</a> add-on is offered by Heroku and provides a hosted MongoDB datastore.</p>
<p>If you decide to try MongoDB, take a look at the example apps (with detailed tutorials) that combine <a href="">Mongoid with Devise</a> or <a href="">Mongoid with OmniAuth</a>.</p>
<h4>Configure Mongoid</h4>
<p>By default, the file <strong>config/mongoid.yml</strong> contains this:</p>
# Configure available database sessions. (required)
# Defines the default session. (required)
# Defines the name of the default database that Mongoid can connect to.
# (required).
database: &lt;something&gt;
# Provides the hosts the default session can connect to. Must be an array
# of host:port pairs. (required)
- localhost:27017
<p>To use MongoHQ with your app, add the following to the file <strong>config/mongoid.yml</strong>:</p>
&lt;% if ENV['MONGOHQ_URL'] %&gt;
uri: &lt;%= ENV['MONGOHQ_URL'] %&gt;
skip_version_check: true
safe: true
&lt;% end %&gt;
<h2>Specifying a Rails Server</h2>
<p>By default, when you run <code>rails server</code> locally, Rails launches the simple Webrick web server. For production apps Heroku recommends using a more robust webserver such as <a href="">Thin</a>.</p>
<p>To use Thin, add the gem to your Gemfile:</p>
<p><code>gem 'thin'</code></p>
<p>If you want to continue to use Webrick as your local web server, with Thin on Heroku, set up your Gemfile like this:</p>
group :production do
gem 'thin'
<p>Run <code>bundle install --without production</code> to update your gems.</p>
<h3>Procfile Not Needed</h3>
<p>Heroku recommends adding a Procfile to your app. 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.</p>
<p>Procfile is a mechanism for declaring what commands are run when your web app runs on the Heroku platform. 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.</p>
<h2>Precompile Assets</h2>
<p>Rails 3.1 introduced the asset pipeline which enables proper organization of <span class="caps">CSS</span> and JavaScript. Assets must be available as Javascript and <span class="caps">CSS</span> files when anyone visits your website. That means multiple files in various formats (CoffeeScript, <span class="caps">SASS</span>, etc.) must be compiled to simple Javascript and <span class="caps">CSS</span> files. During development, assets are compiled on the fly so you can easily make changes and see the results.</p>
<p>For deployment on Heroku, you have three options:</p>
<li>do nothing and allow Heroku to attempt to precompile assets when you deploy to Heroku (slug compilation)</li>
<li>do nothing and allow Heroku to attempt to compile assets when the app is generated (runtime compilation)</li>
<li>precompile the assets before deployment to Heroku</li>
</ul><p>While runtime asset compilation will work, it should be used as a last resort. Using runtime compilation will require Rails to compile your assets each time a dyno boots up increasing the wait time for a new dyno to become available. If you do nothing and rely on Heroku to perform slug compilation (when you deploy to Heroku), you may find Heroku is unable to compile the assets and will default to runtime compilation. It’s best to precompile the assets before deployment to Heroku.</p>
<p>Heroku doesn’t check files in the <strong>config/initializers</strong> folder before attempting to precompile assets. That’s fine if you precompile assets before deploying to Heroku. Or if you don’t use the initializer files to set constants that are used in the assets files. You can avoid these issues by adding this configuration parameter to the <strong>config/application.rb</strong> file:</p>
# Heroku requires this to be false
<p>To precompile assets before deployment to Heroku:</p>
rake assets:precompile
<p>See the article <a href="">Rails 3.1+ Asset Pipeline on Heroku Cedar.</a>.</p>
<h2>Commit to Git</h2>
<p>Your application must be committed to a Git repository before you can use Heroku. See <a href="">Git and Rails</a> to learn how to set up Git for your application.</p>
<p>Store the modified application in the Git repository:</p>
<p><code>$ git commit -am "Configured for deployment to Heroku"</code></p>
<h2>Heroku Account</h2>
<p>To deploy an app to Heroku, you must have a Heroku account. Visit <a href=""></a> to set up an account. Heroku will ask you for your email address; it’s advisable to use the same email address you use for your GitHub account (see the article <a href="">Git and Rails</a>).</p>
<h3>Using a Client’s Account</h3>
<p>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.</p>
<h3>Deploying for Multiple Accounts</h3>
<p>David Dollar’s <a href="">heroku-accounts plugin</a> 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.</p>
<p>To install the heroku-accounts plugin:</p>
heroku plugins:install git://
<p>To add an account locally (which you’ll call “work”):</p>
$ heroku accounts:add work --auto
<p>To list accounts that are set up locally:</p>
$ heroku accounts
<p>To set an account to use for a project:</p>
# in project root
heroku accounts:set work
<h2>Create Your Application on Heroku</h2>
<p>Use the Heroku create command to create and name your new app.</p>
<p><code>$ heroku create myapp</code></p>
<p>Replace <code>myapp</code> with something unique. Heroku demands a unique name for every hosted application. If it is not unique, you’ll see an error, “name is already taken.”</p>
<p>As of June 20, 2012, Heroku’s <a href="">default stack changed to Cedar</a>. Before, you needed to specify <code>$ heroku create myapp --stack cedar</code>; that’s no longer necessary.</p>
<p>If you don’t specify your app name (<code>myapp</code> in the example above), Heroku will supply a placeholder name. You can easily change Heroku’s placeholder name to a name of your choice with the <code>heroku apps:rename command</code> (see <a href="">Renaming Apps from the <span class="caps">CLI</span></a>).</p>
<p>Don’t worry too much about getting the “perfect name” for your Heroku app. The name of your Heroku app won’t matter if you plan to set up your Heroku app to use your own domain name. You’ll just use the name for access to the instance of your app running on the Heroku servers; later, you’ll set up <span class="caps">DNS</span> to point your domain name to the app running on Heroku.</p>
<h3>Set Heroku Environment Variables</h3>
<p>Your application may be obtaining usernames, passwords, or <span class="caps">API</span> keys for external services from the Unix shell environment. It’s a recommended practice to avoid recording sensitive information in your application code where it might be exposed publicly on a GitHub repo.</p>
<p>After create the Heroku app, you may need to set Heroku environment variables to provide the same data your application obtains from your local shell environment.</p>
<p>For example, for Gmail:</p>
$ heroku config:add GMAIL_PASSWORD=secret
<h3>Check Heroku Configuration</h3>
<p>You can check that everything has been added correctly by running:</p>
<p><code>$ heroku info --app myapp</code></p>
<h2>Using MongoDB</h2>
<p>If you are using MongoDB, you can use a Heroku add-on to deploy your app using the MongoHQ service. See <a href="">details about the service</a> and <a href="">details about installation</a>.</p>
<p>To use MongoDB with your app, enable the add-on with the following command:</p>
<p><code>$ heroku addons:add mongohq:free</code></p>
<h4>Troubleshooting Problems Connecting to MongoHQ</h4>
<p>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 <strong>config/mongoid.yml</strong> file may not have the correct MongoHQ connection parameters.</p>
<h2>Push Your Application to Heroku</h2>
<p>Push your application to Heroku:</p>
<p><code>$ git push heroku master</code></p>
<p>Review the output carefully. If you precompiled assets before deploying, you should see:</p>
-&gt; Preparing app for Rails asset pipeline
Detected manifest.yml, assuming assets were compiled locally
<p><em>Note:</em> 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.</p>
<h4>Database Migrations</h4>
<p>You’ll need to run your database migrations (not applicable if you are using MongoDB):</p>
<p><code>$ heroku run rake db:migrate</code></p>
<p>Initialize your application database if your application requires it:</p>
<p><code>$ heroku run rake db:seed</code></p>
<p>These two commands can be combined as:</p>
<p><code>$ heroku run rake db:setup</code></p>
<h4>PostgreSQL Database Reset</h4>
<p>Heroku doesn’t support <code>rake db:reset</code>.</p>
<p>Need to reset your Heroku PostgreSQL database? Here’s how:</p>
<p><code>$ heroku pg:reset SHARED_DATABASE --confirm myapp</code></p>
<p>Don’t forget to restart your application or you won’t see any changes:</p>
<p><code>$ heroku restart</code></p>
<h2>Visit Your Site</h2>
<p>Open your Heroku site in your default web browser:</p>
<p><code>$ heroku open</code></p>
<p>Your app will be running at <a href=""></a>.</p>
<h2>Enabling Email</h2>
<p>Unless you enable email on Heroku, you’ll get errors when your application tries to send email from Heroku.</p>
<p>Heroku offers several options for sending email from your Rails application. See Heroku’s documentation <a href="">Sending Email from Your App</a>.</p>
<h3>Email Service Providers</h3>
<p>For a production application, you’ll need to use an email service provider for your transactional email such as <a href="">SendGrid</a> or <a href="">Mandrill</a>.</p>
<p>If you’re sending test emails during development, Gmail is the easiest option.</p>
<p>To use Gmail from Heroku, add the following to your <em>config/environments/production.rb</em> file:</p>
config.action_mailer.default_url_options = { :host =&gt; '' }
config.action_mailer.delivery_method = :smtp
config.action_mailer.perform_deliveries = true
config.action_mailer.raise_delivery_errors = false
config.action_mailer.default :charset =&gt; "utf-8"
config.action_mailer.smtp_settings = {
address: "",
port: 587,
domain: "",
authentication: "plain",
enable_starttls_auto: true,
user_name: ENV["GMAIL_USERNAME"],
<p>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 <a href="">Configuration and Config Vars</a>.</p>
<p>Set your Gmail username and password as Heroku environment variables:</p>
$ heroku config:add GMAIL_PASSWORD=please
<h2>Your Own Domain</h2>
<p>You’ll likely want to use your own domain name for your app.</p>
<p>See <a href="">Heroku’s article about custom domains</a> for instructions.</p>
<h3>Why “www” Matters</h3>
<p>For simplicity, you might want your web app running on a “bare domain” like <a href=""></a>. You can do it, but Heroku explains <a href="">Why You Should Avoid Naked Domains</a> and always use a <a href="">fully qualified domain name</a> such as <a href=""></a>.</p>
<h3>Set Your Domain Name</h3>
<p>This command tells Heroku that your app should respond to requests to “”:</p>
$ heroku domains:add
<h3>Set a <span class="caps">DNS</span> Record</h3>
<p>Domain Name Service (<a href=""><span class="caps">DNS</span></a>) routes requests for your domain to the servers that host your application. Your name service may be provided by your domain registrar (for example, GoDaddy) or a managed <span class="caps">DNS</span> provider (for example, <a href="">DNSimple</a> or <a href="">Zerigo</a>). You must visit your <span class="caps">DNS</span> provider’s website to set a <span class="caps">CNAME</span> record to route requests for “” to your app running on Heroku.</p>
<p>Each <span class="caps">DNS</span> provider has a different interface for managing <span class="caps">DNS</span> records. This article doesn’t show you how to set a <span class="caps">CNAME</span> record.</p>
<p>After you have set a <span class="caps">CNAME</span> record, as soon as <span class="caps">DNS</span> records propagate (usually a few minutes but sometimes longer), your app should be running at <a href=""></a>.</p>
<h3>Using Subdomains</h3>
<p>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),</p>
$ heroku domains:add *
<p>Then, visit your <span class="caps">DNS</span> provider to set a <span class="caps">CNAME</span> record to point “*” at “”.</p>
<h3>Checking Subdomains</h3>
<p>You can check that everything has been added correctly by running:</p>
$ heroku info --app myapp
<p>As soon as <span class="caps">DNS</span> has propagated, your local computer will show that the domain name resolves properly:</p>
$ host has address ...
<p>When you get errors, troubleshoot by reviewing the log files:</p>
$ heroku logs
<p>If necessary, use the Unix tail flag to monitor your log files. Open a new terminal window and enter:</p>
$ heroku logs -t
<p>to watch the server logs in real time.</p>
<h4>Where to Get Help</h4>
<p>Your best source for help with Heroku is <a href="">Stack Overflow</a>. Your issue may have been encountered and addressed by others.</p>
<p>You can also check the <a href="">Heroku Dev Center</a> or the <a href="">Heroku Google Group</a>.</p>
</div><!-- class="content" -->
<div class="comments">
<div class="content wikistyle gollum">
<h2>Comments and Issues</h2>
<p>Is this helpful? Please add a comment below. Your encouragement fuels the project.</p>
<p>Did you find an error? Or couldn't get something to work? For the example apps and tutorials, please create a GitHub issue in the repository for the example app. Creating a GitHub issue is the best way to make sure a problem is investigated and fixed.</p>
<div id="disqus_thread"></div>
<script type="text/javascript">
var disqus_shortname = 'railsapps'; // required: replace example with your forum shortname
(function() {
var dsq = document.createElement('script'); dsq.type = 'text/javascript'; dsq.async = true;
dsq.src = 'http://' + disqus_shortname + '';
(document.getElementsByTagName('head')[0] || document.getElementsByTagName('body')[0]).appendChild(dsq);
<noscript>Please enable JavaScript to view the <a href="">comments powered by Disqus.</a></noscript>
<a href="" class="dsq-brlink">comments powered by <span class="logo-disqus">Disqus</span></a>
</div><!-- class="comments" -->
<div class="footer row">
<div class="span4">
<p><a href="">Daniel Kehoe</a> initiated the <a href="">RailsApps Project</a>. Thanks to all the users and contributors.</p>
<div class="span4">
<p>Corrections? Additions? You can edit this page <a href="">on the wiki</a>.</p>
<div class="span4">
<h3>Last edit</h3>
<p>by <b>Daniel Kehoe</b>, 2012-07-20 23:08:42</p>