People are often asking us about how to install Spree on the popular Heroku service. For those of you who don't know what Heroku is, its a popular cloud-based hosting choice for Rails applications. The reason why people have a lot of questions about Heroku specifically is due to the unique design of the Heroku platform which presents a few constraints not found in a typical Rails hosting environment.

Assumptions

This is not a how-to guide for Rails applications in general. So lets start off with a few assumptions about your system. You can easily Google for some additional information if you do not have the following installed on your system:

• Ruby
• ImageMagick
• Git
• Rubygems
• bundler gem
• heroku gem

ImageMagick is not strictly necessary - it is only needed if you plan to upload new pictures for your products. It is also installed by default on Heroku so it will only be a limitation for you in terms of testing the product image upload locally.

Amazon S3 Account

The primary limitation of Heroku is that it contains a read-only filesystem. This means that you cannot simply upload images to the server for your products. The images need to be stored on a third-party service such as Amazon's Simplified Storage System (S3). We will save the details for configuring Spree to work with S3 for a separate blog post. For now we'll just be satisfied to deploy a basic Spree store.

Creating a Basic Spree Application

We'll start by creating a basic Rails application.

$ rails new spree_demo
$ cd spree_demo
$ bundle install
$ git init
$ git add .
$ git commit -m "First commit"

Now we'll add the Spree gem by editing the Gemfile in the spree_demo application as follows:

gem 'spree'

Once this is done we can install the necessary migrations, etc.

$ rails g spree:site
$ rake spree:install
$ rake spree_sample:install
$ rake db:bootstrap

Now we'll do another git commit to save our progress.

$ git add .
$ git commit -m "Added Spree"

Heroku Code Tweaks

Now comes the stuff that is specfic to Heroku. We'll start by editing edit config/environments/production.rb as follows:

config.action_controller.perform_caching = false

This tells Rails that the stylesheets and javascript stuff should not be cached in the read-only filesystem (which is not possible on Heroku.) Once again we perform a git commit to save our progress.

$ git add .
$ git commit -m "Heroku tweaks"

Creating the Heroku App

Its pretty simple to create a new Heroku application from an existing Rails application already under source control with Git.

NOTE: The following example uses an application name of heroku-spree. Each Heroku application needs a unique name so you will have to choose your a name that is not already in use.

$ heroku create heroku-spree
Creating heroku-spree....... done
http://heroku-spree.heroku.com/ | git@heroku.com:heroku-spree.git
Git remote heroku added

Now we'll deploy the Heroku application:

$ git push heroku master
heroku db:push
heroku restart

Heroku Configuration

Spree requires SSL for checkout in production mode (and this is the default mode for Heroku applications.) So we'll use the Heroku gem to configure a simple wildcard SSL certificate. We'll also enable the Sendgrid add-on to send emails.

$ heroku addons:add piggyback_ssl
$ heroku addons:add sendgrid:free

These are free add on services for testing purposes. You will need your own SSL certificate eventually when you deploy to production.

Spree Configuration

You should now be up and running on Heroku! The final step is to configure Spree itself so that you can do a complete checkout. To do this, just log into the admin interface and create a production payment method that uses the Gateway::Bogus gateway. For more information on configuring a payment method see the official Spree documentation.