Heroku_san is a gem that helps streamline setup and deployment of apps on Heroku. Today I’m going to add heroku_san to the Foo vs. Baz project, and I’ll use it to create a staging site.

Install the gem

First I’ll add this to the :test, :development block. (You don’t need it in production.)

gem "heroku_san", "~> 4.2.1"

Then run bundle install.

Create a config

First generate a basic config file by running this:

$ rails g heroku_san

Right now, I want to just get things working for the existing app, so I’m going to comment out the staging and demo sections, and just focus on production.

Since FvB is a very simple application with only one addon, the config for it is very simple:

  app: foo-vs-baz
  stack: cedar
  addons: &default_addons
    - heroku-postgresql:dev

That’s it! (The &default_addons bit will come in handy when we create the staging app.)

If you already have an app up and running, you can run heroku addons to see the list of addons already in your app. To make it easy to setup a staging env it’s a good idea to put all of your addons in the heroku_san config file. This will allow you to easily replicate your environment.


Now I can deploy the app to heroku with :

$ rake production deploy

Create a staging env

Since all good apps need a staging env, let’s get one setup for FvB. First, I just add this to the heroku_san config file:

  stack: cedar
  app: foo-vs-baz-staging
  addons: *default_addons

Then I run this at the console to create the new staging app on heroku and to set the RAILS_ENV variable in the heroku config.

$ rake staging heroku:create heroku:rack_env

Now I’m ready to deploy the staging app:

$ rake staging deploy

Heroku_san pushes the code to the new staging app, runs migrations on the database, and restarts the workers. So now, there’s a fully functioning staging version of FvB (Note : I will probably turn on maintenance mode for the staging app at some point in the near future.)


For a simple app like this, that was already deployed, it made sense to use the production app as the master reference for addons and to let the staging app use the same ones as production. Well, OK, one. For a real app you may not want to use exactly the same addons in staging and production. For instance if your app uses ElasticSearch, in staging you might want to go with the staging level plan at Bonsai.io, but for production you’ll need a bigger one. In that case you may want to structure your heroku_san config file a little differently.