Ruby Journal

Spree 1.1 Deployment on Heroku

| Comments

In this tutorial, I will show you how to create a Spree application on your local box, configure and push it to Heroku.




Prerequisites

All instructions are written for OSX 10.8.x system. However it also works to UNIX and Linux systems with minor adaptations.

Heroku

If you have installed Heroku, please make sure you update to version 2.1.0 or higher for Cedar support:

1
2
3
$ heroku update
$ heroku --version
heroku-toolbelt/2.35.0 (x86_64-darwin10.8.0) ruby/1.9.3

Ruby

Because we are going to deploy on Heroku Cedar stack with Ruby 1.9.3 chosen as default version. We should use the same Ruby version on our local box for consistency.

1
$ rvm install 1.9.3

Spree

1
$ gem install spree -v=1.1.7

Check installed spree gems:

1
2
3
4
5
6
7
8
9
$ gem list | grep 'spree'
spree (1.1.7)
spree_api (1.1.7)
spree_auth (1.1.7)
spree_cmd (1.1.7)
spree_core (1.1.7)
spree_dash (1.1.7)
spree_promo (1.1.7)
spree_sample (1.1.7)

spree gem consists of many components, however you only need spree_core to build an online store.

PostgreSQL

Heroku only support PostgreSQL and the software can be installed with Homebrew:

1
$ brew install postgresql

Please make sure you read the Build Notes after the installation.

Additionally, pg is installed to provide DB adapter:

1
$ gem install pg

Other dependencies

1
$ brew install imagemagick

Prepare local application

Create a new rails app default to postgreSQL

1
rails _3.2.12_ new fool-man-chew -d postgresql

Configure database setting by editing config/database.yml.

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
development:
  adapter: postgresql
  encoding: unicode
  database: fool-man-chew_development
  pool: 5
  username: your_username
  password: your_password

test:
  adapter: postgresql
  encoding: unicode
  database: fool-man-chew_development
  pool: 5
  username: your_username
  password: your_password

production:
  adapter: postgresql
  encoding: unicode
  database: fool-man-chew_development
  pool: 5
  username: your_username
  password: your_password

In fact, you could remove production from config/database.yml because Heroku doesn’t create db based on local box config/database.yml file though.

Don’t forget to create databases with:

1
$ bundle exec rake db:create:all

Bootstraping on local box

There are two ways to bootstrap Spree, I prefer the latter method as it gives me more control of bootstraping process.

Both ways runs Asset Precompiling rake task which fix an issue where Heroku could not precompile asset, you could read more about this issue at Assets Precompiling section

1. Wizard mode

spree_cmd gem provides the convenient spree command that add the Spree gem, create initializers, copy migrations and optionally generate sample products and orders.

1
$ RAILS_ENV=development spree install fool-man-chew

You can notice that I explicitly declare RAILS_ENV=development here. If not, spree install will assume your RAILS_ENV=production

The wizard will guide you through a list of questions, I opt no for Default Gateway because I am not going to use skrill gateway for this tutorial.

1
2
3
4
5
6
Would you like to install the default gateways? (yes/no) [yes] no
Would you like to run the migrations? (yes/no) [yes] yes
Would you like to load the seed data? (yes/no) [yes] yes
Would you like to load the sample data? (yes/no) [yes] yes
Admin Email [spree@example.com] fool@man.ch
Admin Password [spree123] foo123

if nothing goes wrong, you would see:

1
2
3
4
5
6
7
8
9
10
11
12
13
...
     loading  seed data
     loading  sample data
      insert  config/routes.rb
**************************************************
We added the following line to your application's config/routes.rb file:

    mount Spree::Core::Engine, :at => '/'
**************************************************
Spree has been installed successfully. You're all ready to go!

Enjoy!
precompiling  assets

2. Manual mode

You could manually append spree gem into the end of your Gemfile:

1
gem 'spree', '~> 1.1.7'

If you have not yet run bundle install, please run it now:

1
$ bundle install

Next we invoke Spree install generator to copy migrations, initializers and generate sample data:

1
$ rails g spree:install

OR

Bootstraping manually with command:

1
2
3
4
$ bundle exec rake spree:install:migrations
$ bundle exec rake db:migrate
$ bundle exec rake db:seed
$ bundle exec rake spree_sample:load

Once the bootstrap is finished, we need to precompile our assets too:

1
$ bundle exec rake assets:precompile:nondigest

Deploy to Heroku

Configure web server

By default, Heroku use the Thin server. However in this tutorial, we are going to use Puma instead, just to show you the great new process types system that Cedar support.

Append to Gemfile:

1
2
3
group :production do
  gem 'puma'
end

and install the gem with:

1
$ bundle install

Then we set up Puma to use minium 4 threads. You can scale up to more Dynos should the app need more processing power. Create a new file config/puma.rb:

1
threads 4, 16

The great about Cedar stack is that Heroku introduces a new way to scale your app, that is Process Model, now you could define a custom list of process type that you want to run in the Procfile file.

We configure our unicorn which is of type web by creating new file in Rails.root folder Procfile:

1
web: bundle exec puma -p $PORT -C ./config/puma.rb

Heroku setup

Create Heroku app

We are going to create an Cedar stack based app:

1
$ heroku apps:create fool-man-chew

If success, you would see below output:

1
2
3
Creating fool-man-chew... done, stack is cedar
http://fool-man-chew.herokuapp.com/ | git@heroku.com:fool-man-chew.git
Git remote heroku added

and double check git remote you would see heroku remote listed:

1
2
$ git remote show
heroku

Install ruby-1.9.3 for Heroku

Cedar stack default to ruby-1.9.3.

We specify Ruby version in the Gemfile:

1
2
3
source 'http://rubygems.org'

ruby '1.9.3'

Set up Amazon S3

Heroku is diskless, thus assets storage is delegated to third-party cloud storage service like Amazon S3.

Add SSL certificate

By default, Spree production mode enforce SSL. This step is very optional, please read Disable SSL in Production section if you want to disable SSL in Production mode.

A Piggyback SSL is a now standard feature on all Heroku apps so you don’t have to enable. We are not going to buy a certificate for this test app. Instead, we are going to set up a Self-Signed SSL Certificate.

A private key and certificate signing request can be generated:

1
2
3
4
5
6
7
8
9
10
11
12
13
$ openssl genrsa -des3 -out site.key 2048
    ...
   Enter pass phrase for site.key:
   Verifying - Enter pass phrase for site.key:
$ mv site.key site.orig.key
$ openssl rsa -in site.orig.key -out site.key
   Enter pass phrase for site.orig.key:
   writing RSA key
$ openssl req -new -key site.key -out site.csr
   ...
   Country Name (2 letter code) [AU]:US
   State or Province Name (full name) [Some-State]:California
   ...

and now the self-signed SSL certificate is generated from the site.key private key and site.csr files:

1
$ openssl x509 -req -days 365 -in site.csr -signkey site.key -out final.crt

The final.crt file is your site certificate suitable for use with Heroku’s SSL add-on along with the site.key private key.

Now we upload those two files to Heroku:

1
2
$ heroku domains:add fool-man-chew.herokuapp.com
$ heroku ssl:add final.crt site.key

Bootstraping Spree on Heroku

Now we could push our app to Heroku:

1
2
3
4
git init
git add -A
git commit -m "Initial commit"
git push heroku master

OPTIONAL: If you ever bump into issues where Bundler fails to locate gems, the best workaround is to cache the bundle:

1
2
3
bundle cache
git add -A
git commit -m 'Bundle cache'

If all goes well, you would see following output:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
-----> Heroku receiving push
-----> Ruby/Rails app detected
-----> Using RUBY_VERSION: ruby-1.9.3-p392
-----> Installing dependencies using Bundler version 1.3.0.pre5
       Running: bundle install --without development:test --path vendor/bundle --binstubs bin/ --deployment
       Fetching gem metadata from http://rubygems.org/.......
       Fetching gem metadata from http://rubygems.org/..
       Fetching git://github.com/joneslee85/spree-heroku.git
       ....
       Writing config/database.yml to read from DATABASE_URL
-----> Preparing app for Rails asset pipeline
       Detected manifest.yml, assuming assets were compiled locally
-----> Rails plugin injection
       Injecting rails_log_stdout
       Injecting rails3_serve_static_assets
-----> Discovering process types
       Procfile declares types      -> web
       Default types for Ruby/Rails -> console, rake, worker
-----> Compiled slug size is 39.4MB
-----> Launching... done, v9
       http://fool-man-chew.herokuapp.com deployed to Heroku

Next we could repeat the same bootstraping step on our remote heroku:

1
$ heroku run rails g spree:install

Now we could open app:

1
$ heroku apps:open

Custom Domain

Now we push a bit further by setting up custom domain for our shop, first we need to set up Heroku to respond to requests at custom domains:

1
2
$ heroku addons:add custom_domains
Adding custom_domains to fool-man-chew...done.

And inform Heroku our beautiful fool-man-chew.com domain

1
2
3
4
$ heroku domains:add www.fool-man-chew.com
Added www.example.com as a custom domain name to fool-man-chew.heroku.com
$ heroku domains:add fool-man-chew.com
Added example.com as a custom domain name to fool-man-chew.heroku.com

Then I point the domain DNS to Heroku. Please read more at Heroku Custom Domain

We also need to let Spree know of our custom domain by append site_url in our config/initializers/spree.rb

config/initializers/spree.rb
1
2
3
Spree.config do |config|
  config.site_url = 'fool-man-chew.com'
end

Add, commit and push again:

1
2
3
4
$ git add config/initializers/spree.rb
$ git commit -m 'Use custom domain'
$ git push heroku master
$ git heroku:restart

Issues

Disable SSL in Production mode

Edit file config/initializers/spree.rb:

config/initializers/spree.rb
1
2
3
Spree.config do |config|
  config.allow_ssl_in_production = false
end

Make sure you commit the changes to app repository.

Assets Precompiling

Heroku would fail precompiling assets in slug compilation. Following output show the error:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
   Injecting rails_log_stdout
   Injecting rails3_serve_static_assets
-----> Preparing app for Rails asset pipeline
   Running: rake assets:precompile
   rake aborted!
   could not connect to server: Connection refused
   Is the server running on host "127.0.0.1" and accepting
   TCP/IP connections on port 5432?

   Tasks: TOP => environment
   (See full trace by running task with --trace)
   Precompiling assets failed, enabling runtime asset compilation
   Injecting rails31_enable_runtime_asset_compilation
   Please see this article for troubleshooting help:
   http://devcenter.heroku.com/articles/rails31_heroku_cedar#troubleshooting

It make some sense though because Spree requires access to DB to complete this task and yet before you push to Heroku the environment config is not present.

So we have to disable precompile on intialize by set config.assets.initialize_on_precompile to false in config/application.rb

1
config.assets.initialize_on_precompile = false

Then workaround this issue by locally precompile assets before deployment:

1
$ bundle exec rake assets:precompile RAILS_ENV=development

What will happen next is Sprocket will compile our assets and place them in public/assets folder. What Heroku really care is the public/assets/manifest.yml. This file contains all MD5 checksums of our assets and Heroku will check the existence of the file to tell if we compile our assets locally or not.

If we push this file to our server:

1
2
3
$ git add -A public/assets
$ git commit -m 'Added precompiled assets'
$ git push heroku master

you would see:

1
2
3
4
....
-----> Preparing app for Rails asset pipeline
       Detected manifest.yml, assuming assets were compiled locally
...

You could read more on Rails 3.1 on Heroku

Conclusion

Spree 1.1.x is not a revolutionary change from 1.0.x but it is an incremental changes with bug fixes and updates such as dependency on Rails 3.1.x. I highly recommend you upgrade if you are still on 1.0.x.

Again, I’d extend to the core team to deliver another robust release.

Comments