-
Notifications
You must be signed in to change notification settings - Fork 0
/
Copy pathrails-heroku-tutorial.html
319 lines (309 loc) · 22 KB
/
rails-heroku-tutorial.html
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
<!DOCTYPE html>
<html>
<head>
<meta http-equiv="Content-Type" content="text/html; charset=utf-8"/>
<title>Tutorial: Rails 3.2 with Ruby 1.9.3 on Heroku</title>
<link href="https://plus.google.com/u/0/b/117374718581973393536/117374718581973393536/posts/" rel="publisher" />
<link rel="stylesheet" href="/css/bootstrap.css" type="text/css" charset="utf-8" />
<link rel="stylesheet" href="/css/screen.css" type="text/css" charset="utf-8" />
<link rel="stylesheet" href="/css/gollum.css" type="text/css" charset="utf-8" />
<link rel="stylesheet" href="/css/site.css" type="text/css" charset="utf-8" />
<link rel="stylesheet" href="/css/syntax.css" type="text/css" charset="utf-8" />
<script src="http://code.jquery.com/jquery-1.6.min.js" type="text/javascript"></script>
<script src="/javascript/jquery.text_selection-1.0.0.min.js" type="text/javascript"></script>
<script src="/javascript/jquery.previewable_comment_form.js" type="text/javascript"></script>
<script src="/javascript/jquery.tabs.js" type="text/javascript"></script>
<script src="/javascript/gollum.js" type="text/javascript"></script>
<script type="text/javascript">
var _gaq = _gaq || [];
_gaq.push(['_setAccount', 'UA-5109366-14']);
_gaq.push(['_trackPageview']);
(function() {
var ga = document.createElement('script'); ga.type = 'text/javascript'; ga.async = true;
ga.src = ('https:' == document.location.protocol ? 'https://ssl' : 'http://www') + '.google-analytics.com/ga.js';
var s = document.getElementsByTagName('script')[0]; s.parentNode.insertBefore(ga, s);
})();
</script>
</head>
<body>
<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="http://blog.railsapps.org/" class="twitter">Blog</a></li>
<li><a href="http://twitter.com/rails_apps" class="twitter">Twitter</a></li>
<li><a href="https://plus.google.com/117374718581973393536" class="google">Google +</a></li>
<li><a href="https://github.com/RailsApps" class="github">GitHub Repository</a></li>
</ul>
</div>
</div>
</div>
<div class="container">
<div class="page-header">
<h1>Tutorial: Rails 3.2 with Ruby 1.9.3 on Heroku</h1>
</div>
<div class="content wikistyle gollum textile">
<h1>Tutorial: Rails 3.2 with Ruby 1.9.3 on Heroku</h1>
<h4>by Daniel Kehoe</h4>
<p><em>Last updated 10 May 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. See a discussion on Quora <a href="http://www.quora.com/What-are-the-potential-downsides-of-using-Heroku">What are the potential downsides of using Heroku?</a> (not many).</p>
<p><strong>Update! Heroku now officially gives you a choice of Ruby versions, including 1.9.3. See <a href="http://blog.heroku.com/archives/2012/5/9/multiple_ruby_version_support_on_heroku/">Multiple Ruby Version Support on Heroku</a>.</strong></p>
<p>See <a href="http://railsapps.github.com/installing-rails.html">Installing Rails 3.2</a> for advice and suggestions on setting up the newest version of Rails on your own computer.</p>
<p>This is a guide for developers using the starter apps from the <a href="http://railsapps.github.com/">Rails Apps</a> repository. Others may find it helpful as well.</p>
<p>See a list of recommended resources for <a href="http://railsapps.github.com/rails.html">Rails</a>.</p>
<p><a href="http://www.twitter.com/rails_apps"><img src="http://twitter-badges.s3.amazonaws.com/t_logo-a.png" title="Follow on Twitter" alt="Follow on Twitter"></a> Follow <a href="http://twitter.com/rails_apps">@rails_apps</a> on Twitter for updates and timely Rails tips.</p>
<h2>Heroku Gem</h2>
<p>Add the Heroku gem to your application’s Gemfile <a href="http://rubygems.org/gems/heroku">(check rubygems.org 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="http://devcenter.heroku.com/articles/keys">Managing Your <span class="caps">SSH</span> Keys</a>.</p>
<p>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="http://devcenter.heroku.com/articles/heroku-command">Installing the Heroku <span class="caps">CLI</span></a>.</p>
<h2>Heroku Account</h2>
<p>To deploy an app to Heroku, you must have a Heroku account. Visit <a href="http://heroku.com/">http://heroku.com/</a> to set up an account.</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="https://github.com/ddollar/heroku-accounts">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>
<pre>
heroku plugins:install git://github.com/ddollar/heroku-accounts.git
</pre>
<p>To add an account locally (which you’ll call “work”):</p>
<pre>
$ heroku accounts:add work --auto
</pre>
<p>To list accounts that are set up locally:</p>
<pre>
$ heroku accounts
</pre>
<p>To set an account to use for a project:</p>
<pre>
# in project root
heroku accounts:set work
</pre>
<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>
<pre>
group :development, :test do
gem 'sqlite3'
end
group :production do
gem 'pg'
end
</pre>
<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>I recommend considering MongoDB as an alternative. It simplifies development by eliminating the schemas and migrations required by SQLite, MySQL, or PostgreSQL. The <a href="http://addons.heroku.com/mongohq">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="https://github.com/RailsApps/rails3-mongoid-devise">Mongoid with Devise</a> or <a href="https://github.com/RailsApps/rails3-mongoid-omniauth">Mongoid with OmniAuth</a>.</p>
<h4>Configure Mongoid</h4>
<p>By default, the file <strong>config/mongoid.yml</strong> contains this:</p>
<pre>
# 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'] %>
</pre>
<p>To use MongoDB with your app, modify the file <strong>config/mongoid.yml</strong> to look like this:</p>
<pre>
# set these environment variables on your prod server
production:
uri: <%= ENV['MONGOHQ_URL'] %>
</pre>
<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="http://code.macournoyer.com/thin/">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>
<pre>
group :production do
gem 'thin'
end
</pre>
<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. 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.</p>
<p>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>
<h2>Commit to Git</h2>
<p>Your application must be committed to a Git repository before you can use Heroku. See <a href="http://railsapps.github.com/rails-git.html">Using Git with 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>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 --stack cedar</code></p>
<p>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.”</p>
<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>Ruby 1.9.3 and Rails 3.2 on Heroku</h2>
<p>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.</p>
<p>You can configure the Heroku environment to use Ruby 1.9.3.</p>
<p><em>Note:</em> 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.</p>
<p><em>Note:</em> 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.</p>
<p>Enable the “user_env_compile” feature (see Heroku’s <a href="http://devcenter.heroku.com/articles/labs-user-env-compile">documentation</a>):</p>
<p><code>$ heroku labs:enable user_env_compile -a myapp</code></p>
<p>Set the RUBY_VERSION variable:</p>
<p><code>$ heroku config:add RUBY_VERSION=ruby-1.9.3-p125</code></p>
<p>Set the Heroku <span class="caps">PATH</span> config variable to include “bin”:</p>
<p><code>$ heroku config:add PATH=bin:vendor/bundle/ruby/1.9.1/bin:/usr/local/bin:/usr/bin:/bin</code></p>
<p>(Yes, the library path includes “1.9.1”: that’s not a typo.)</p>
<p>You can check that everything has been configured correctly by running:</p>
<p><code>$ heroku config</code></p>
<h4>Documentation for Rails 3.0 and Rails 3.1</h4>
<p>Heroku has no specific documentation for Rails 3.2 but the following articles on Rails 3.0 and Rails 3.1 are helpful:</p>
<ul>
<li><a href="http://devcenter.heroku.com/articles/rails3">Getting started with Rails 3 on Heroku/Cedar</a></li>
<li>
<a href="http://devcenter.heroku.com/articles/rails31_heroku_cedar">Rails 3.1 on Heroku Cedar</a>.</li>
</ul><p><em>Note:</em> 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>
<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="http://addons.heroku.com/mongohq">details about the service</a> and <a href="http://devcenter.heroku.com/articles/mongohq">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>
<p>The file <strong>config/mongoid.yml</strong> should look like this:</p>
<pre>
# set these environment variables on your prod server
production:
uri: <%= ENV['MONGOHQ_URL'] %>
</pre>
<h2>Push Your Application to Heroku</h2>
<p>Push your application to Heroku:</p>
<p><code>$ git push heroku master</code></p>
<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="http://my-app-name.herokuapp.com/">http://my-app-name.herokuapp.com/</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="http://devcenter.heroku.com/articles/smtp">Sending Email from Your App</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>
<pre>
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"]
}
</pre>
<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="http://devcenter.heroku.com/articles/config-vars">Configuration and Config Vars</a>.</p>
<p>Set your Gmail username and password as Heroku environment variables:</p>
<pre>
$ heroku config:add [email protected] GMAIL_PASSWORD=please
</pre>
<h2>Your Own Domain</h2>
<p>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 <a href="http://addons.heroku.com/zerigo_dns">Zerigo <span class="caps">DNS</span> add-on</a>. See <a href="http://devcenter.heroku.com/articles/zerigo">Heroku’s article about setting up Zerigo <span class="caps">DNS</span></a> and <a href="http://devcenter.heroku.com/articles/custom-domains">Heroku’s article about custom domains</a> for more information.</p>
<h3>Use Zerigo’s Nameservers</h3>
<p>Visit your domain registrar and set your domain’s nameserver records to point to Zerigo’s <span class="caps">DNS</span> servers:</p>
<pre>
a.ns.zerigo.net
b.ns.zerigo.net
c.ns.zerigo.net
d.ns.zerigo.net
e.ns.zerigo.net
</pre>
<h3>Enable Custom Domains</h3>
<p>Use the command line to enable Heroku to use a custom domain for your app:</p>
<pre>
$ heroku addons:add custom_domains:basic
</pre>
<h3>Enable the Zerigo <span class="caps">DNS</span> Add-on</h3>
<p>Use the command line to enable the <a href="http://addons.heroku.com/zerigo_dns">Zerigo <span class="caps">DNS</span> add-on</a>:</p>
<pre>
$ heroku addons:add zerigo_dns:basic
</pre>
<h3>Set Your Domain Name</h3>
<p>With the Zerigo <span class="caps">DNS</span> add-on enabled, domain names added via the command line will automatically be added to Zerigo’s <span class="caps">DNS</span> servers. Updates happen instantly and Heroku keeps the <span class="caps">DNS</span> records up-to-date should Heroku change the IP addresses of its servers.</p>
<p>This command tells Heroku that your app should respond to requests to “mydomain.com”:</p>
<pre>
$ heroku domains:add mydomain.com
</pre>
<p>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="http://mydomain.com/">http://mydomain.com/</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>
<p><code>$ heroku addons:add wildcard_domains</code></p>
<p><code>$ heroku domains:add *.mydomain.com</code></p>
<p>You can check that everything has been added correctly by running:</p>
<p><code>$ heroku info --app myapp</code></p>
<h2>Troubleshooting</h2>
<p>When you get errors, troubleshoot by reviewing the log files:</p>
<p><code>$ heroku logs</code></p>
<h4>Where to Get Help</h4>
<p>Your best source for help with Heroku is <a href="http://stackoverflow.com/questions/tagged/heroku">Stack Overflow</a>. Your issue may have been encountered and addressed by others.</p>
<p>You can also check the <a href="http://devcenter.heroku.com/">Heroku Dev Center</a> or the <a href="http://groups.google.com/group/heroku/">Heroku Google Group</a>.</p>
</div><!-- class="content" -->
<div class="comments">
<div class="content wikistyle gollum">
<h2>Comments</h2>
</div>
<p>Is this helpful? Please "like" below. Question or suggestion? Please add a comment below. Got a correction or addition? You can edit this page <a href="https://github.com/RailsApps/railsapps.github.com/wiki/_pages">on the wiki</a> or create a <a href="https://github.com/RailsApps/railsapps.github.com/issues">GitHub issue</a> to alert me.</p>
<div id="disqus_thread"></div>
<script type="text/javascript">
/* * * CONFIGURATION VARIABLES: EDIT BEFORE PASTING INTO YOUR WEBPAGE * * */
var disqus_shortname = 'railsapps'; // required: replace example with your forum shortname
/* * * DON'T EDIT BELOW THIS LINE * * */
(function() {
var dsq = document.createElement('script'); dsq.type = 'text/javascript'; dsq.async = true;
dsq.src = 'http://' + disqus_shortname + '.disqus.com/embed.js';
(document.getElementsByTagName('head')[0] || document.getElementsByTagName('body')[0]).appendChild(dsq);
})();
</script>
<noscript>Please enable JavaScript to view the <a href="http://disqus.com/?ref_noscript">comments powered by Disqus.</a></noscript>
<a href="http://disqus.com" class="dsq-brlink">comments powered by <span class="logo-disqus">Disqus</span></a>
</div><!-- class="comments" -->
<div class="footer row">
<div class="span4">
<h3>Credits</h3>
<p><a href="http://danielkehoe.com/">Daniel Kehoe</a> initiated the <a href="http://railsapps.github.com/">RailsApps Project</a>. Thanks to <a href="http://tigrish.com/">Christopher Dell</a> for design contributions.</p>
</div>
<div class="span4">
<h3>Contributions</h3>
<p>Corrections? Additions? You can edit this page <a href="https://github.com/RailsApps/railsapps.github.com/wiki/_pages">on the wiki</a>.</p>
</div>
<div class="span4">
<h3>Last edit</h3>
<p>by <b>Daniel Kehoe</b>, 2012-05-19 20:21:06</p>
</div>
</div>
</div>
</body>
</html>