Getting Started with Rails 3.0 on Heroku/Cedar

Getting Started with Rails 3.0 on Heroku/Cedar

Last Updated: 21 December 2011

cedar rails ruby

Table of Contents

• Prerequisites
• Install the Heroku Command-line Client
• Write Your App
• Store Your App in Git
• Deploy to Heroku/Cedar
• Console
• Rake
• Webserver
• Troubleshooting
• Frequently Asked Questions

This quickstart will get you going with Rails 3.0 on the Cedar stack. The Rails 3.1 guide is here. For Sinatra or other Ruby apps, please see the Ruby quickstart.

Prerequisites

• Basic Ruby/Rails knowledge, including an installed version of Ruby 1.9.2, Rubygems, Bundler, and Rails 3.
• Basic Git knowledge, including an installed version of Git.
• Basic knowledge of Heroku, including the latest installed version of the Heroku gem.
• Your application must run on Ruby (MRI) 1.9.2.

Install the Heroku Command-line Client

Install the Heroku client:

$ gem install heroku

Write Your App

You may be starting from an existing app. If not, a vanilla Rails 3 app will serve as a suitable sample app:

$ rails new myapp
$ cd myapp

We highly recommend using PostgreSQL during development. However if you are determined to use sqlite3 during development and PostgreSQL during deployment to Heroku, please see:

How do I use sqlite3 for development and PostgreSQL for Heroku?

Since Heroku provides you a PostgreSQL database for your app, edit yourGemfile and change this line:

gem 'sqlite3'

To this:

gem 'pg'

And re-install your dependencies (to generate a new Gemfile.lock):

$ bundle install

Store Your App in Git

$ git init
$ git add .
$ git commit -m "init"

Deploy to Heroku/Cedar

Create the app on the Cedar stack:

$ heroku create --stack cedar
Creating severe-mountain-793... done, stack is cedar
http://severe-mountain-793.herokuapp.com/ | [email protected]:severe-mountain-793.git
Git remote heroku added

Deploy your code:

$ git push heroku master
Counting objects: 67, done.
Delta compression using up to 4 threads.
Compressing objects: 100% (52/52), done.
Writing objects: 100% (67/67), 86.33 KiB, done.
Total 67 (delta 5), reused 0 (delta 0)

-----> Heroku receiving push
-----> Rails app detected
-----> Installing dependencies using Bundler version 1.1.pre.1
       Checking for unresolved dependencies.
       Unresolved dependencies detected.
       Running: bundle install --without development:test --path vendor/bundle --deployment
       Fetching source index for http://rubygems.org/
       Installing rake (0.8.7)
       ...
       Installing rails (3.0.5)
       Your bundle is complete! It was installed into ./vendor/bundle
-----> Rails plugin injection
       Injecting rails_log_stdout
       Injecting rails3_serve_static_assets
-----> Discovering process types
       Procfile declares types -> (none)
       Default types for Rails -> console, rake, web, worker
-----> Compiled slug size is 8.3MB
-----> Launching... done, v5
       http://severe-mountain-793.herokuapp.com deployed to Heroku

To [email protected]:severe-mountain-793.git
 * [new branch]      master -> master

Before looking at the app on the web, let’s check the state of the app’s processes:

$ heroku ps
Process       State               Command
------------  ------------------  ------------------------------
web.1         up for 5s           bundle exec rails server -p $PORT

The web process is up. Review the logs for more information:

$ heroku logs
2011-03-10T11:10:34-08:00 heroku[web.1]: State changed from created to starting
2011-03-10T11:10:37-08:00 heroku[web.1]: Running process with command: `bundle exec rails server -p 53136`
2011-03-10T11:10:40-08:00 app[web.1]: [2011-03-10 19:10:40] INFO  WEBrick 1.3.1
2011-03-10T11:10:40-08:00 app[web.1]: [2011-03-10 19:10:40] INFO  ruby 1.9.2 (2010-12-25) [x86_64-linux]
2011-03-10T11:10:40-08:00 app[web.1]: [2011-03-10 19:10:40] INFO  WEBrick::HTTPServer#start: pid=12198 port=53136
2011-03-10T11:10:42-08:00 heroku[web.1]: State changed from starting to up

Looks good. We can now visit the app with heroku open.

Console

Cedar allows you to launch a Rails console process attached to your local terminal for experimenting in your app’s environment:

$ heroku run console
Running `bundle exec rails console` attached to terminal... up, ps.1
Loading production environment (Rails 3.0.4)
irb(main):001:0>

Rake

Rake can be run as an attached process exactly like the console:

$ heroku run rake db:migrate

Webserver

By default, your app’s web process runs rails server, which uses Webrick. This is fine for testing, but for production apps you’ll want to switch to a more robust webserver. We recommend Thin.

To use Thin with Rails 3, add it to your Gemfile:

gem 'thin'

and change the command used to launch your web process by creating aProcfile, like this:

Procfile

web: bundle exec rails server thin -p $PORT

Test your Procfile locally using the Foreman gem:

$ gem install foreman
$ foreman start
11:35:11 web.1     | started with pid 3007
11:35:14 web.1     | => Booting Thin
11:35:14 web.1     | => Rails 3.0.4 application starting in development on http://0.0.0.0:5000
11:35:14 web.1     | => Call with -d to detach
11:35:14 web.1     | => Ctrl-C to shutdown server
11:35:15 web.1     | >> Thin web server (v1.2.8 codename Black Keys)
11:35:15 web.1     | >> Maximum connections set to 1024
11:35:15 web.1     | >> Listening on 0.0.0.0:5000, CTRL+C to stop

Looks good, so press Ctrl-C to exit. Deploy your changes to Heroku:

$ git add Gemfile Procfile
$ git commit -m "use thin via procfile"
$ git push heroku

Check ps, you’ll see the web process uses your new command specifying Thin as the webserver:

$ heroku ps
Process       State               Command
------------  ------------------  ------------------------------
web.1         starting for 3s     bundle exec rails server thin -p $..

The logs also reflect that we are now using Thin:

$ heroku logs
2011-03-10T11:38:43-08:00 heroku[web.1]: State changed from created to starting
2011-03-10T11:38:47-08:00 heroku[web.1]: Running process with command: `bundle exec rails server thin -p 34533`
2011-03-10T11:38:50-08:00 app[web.1]: => Booting Thin
2011-03-10T11:38:50-08:00 app[web.1]: => Rails 3.0.4 application starting in production on http://0.0.0.0:34533
2011-03-10T11:38:50-08:00 app[web.1]: => Call with -d to detach
2011-03-10T11:38:50-08:00 app[web.1]: => Ctrl-C to shutdown server
2011-03-10T11:38:50-08:00 app[web.1]: >> Thin web server (v1.2.7 codename No Hup)
2011-03-10T11:38:50-08:00 app[web.1]: >> Maximum connections set to 1024
2011-03-10T11:38:50-08:00 app[web.1]: >> Listening on 0.0.0.0:34533, CTRL+C to stop
2011-03-10T11:38:55-08:00 heroku[web.1]: State changed from starting to up

Troubleshooting

If you push up your app and it crashes (heroku ps shows state crashed), check your logs to find out what went wrong. Here are some common problems.

Failed to require a sourcefile

If your app failed to require a sourcefile, chances are good you’re running Ruby 1.9.1 or 1.8 in your local environment. The load paths have changed in Ruby 1.9. Port your app forward to Ruby 1.9.2 making certain it works locally before trying to push to Cedar again.

Encoding error

Ruby 1.9 added more sophisticated encoding support to the language. Not all gems work with Ruby 1.9 (see isitruby19 for information on a particular gem). If you hit an encoding error, you probably haven’t fully tested your app with Ruby 1.9.2 in your local environment. Port your app forward to Ruby 1.9.2 making certain it works locally before trying to push to Cedar again.

Missing a gem

If your app crashes due to missing a gem, you may have it installed locally but not specified in your Gemfile. You must isolate all local testing usingbundle exec. For example, don’t run ruby web.rb, runbundle exec ruby web.rb. Don’t run rake db:migrate, runbundle exec rake db:migrate.

Another approach is to create a blank RVM gemset to be absolutely sure you’re not touching any system-installed gems:

$ rvm gemset create myapp
$ rvm gemset use myapp

Runtime dependencies on development/test gems

If you’re still missing a gem when you deploy, check your Bundler groups. Heroku builds your app without the development or test groups, and if you app depends on a gem from one of these groups to run, you should move it out of the group.

One common example using the RSpec tasks in your Rakefile. If you see this in your Heroku deploy:

$ heroku run rake -T
Running `bundle exec rake -T` attached to terminal... up, ps.3
rake aborted!
no such file to load -- rspec/core/rake_task

Then you’ve hit this problem. First, duplicate the problem locally like so:

$ bundle install --without development:test
...
$ bundle exec rake -T
rake aborted!
no such file to load -- rspec/core/rake_task

Now you can fix it by making these Rake tasks conditional on the gem load. For example:

Rakefile

begin
  require "rspec/core/rake_task"

  desc "Run all examples"
  RSpec::Core::RakeTask.new(:spec) do |t|
    t.rspec_opts = %w[--color]
    t.pattern = 'spec/*_spec.rb'
  end
rescue LoadError
end

Confirm it works locally, then push to Heroku.