1 Prerequisites

  • Git – Heroku relies on Git being installed on your system. You should install it beforehand.
  • Heroku – If you haven’t done so already, follow the first two steps of the Getting Started on Heroku with Ruby. They cover signing up for Heroku, installing the Heroku client, and logging in through the client.

2 Creating a new Refinery application on Heroku

First you need to install Refinery. To do that you need the refinerycms gem.

gem install refinerycms

Now it’s time to create your Refinery application using the built in --heroku option:

refinerycms myapp --heroku

Watch the output for these lines:

Creating Heroku app..
Running: cd /path/to/app/myapp && heroku create
Creating random-site-name..... done
Created http://random-site-name.herokuapp.com/

This will output the URL for your Heroku-hosted Refinery application. Your application should now be live at http://random-site-name.heroku.com.

that you may have issues precompiling your assets, which may result in system images not loading. Skip to the following Step 3 for a fix.

3 Deploying an existing local Refinery application

If you have already built a Refinery application locally, you’ll need to make some changes to be able to deploy to Heroku.

3.1 Step 1: Update the Gemfile

3.1.1 If your local database is not PostgreSQL

You don’t have to change your local database settings to use PostgreSQL, but Heroku depends on the presence of the pg gem. So, in your Gemfile, change:

gem 'sqlite3' # or whatever the database driver for your local database is


group :development, :test do
  gem 'sqlite3'
group :production do
  gem 'pg'

Using differing databases for development and production is not recommended. Occasionally, specific Rails idioms may have different effects on different databases. We encourage you to set up and develop on PostgreSQL if you intend to deploy your application to Heroku.

3.1.2 Others additions to append in the Gemfile
ruby 2.3.1 # or the newest version of Ruby

group :production do
  gem 'dragonfly-s3_data_store'
  gem 'rails_12factor'
  gem 'puma'
3.1.3 Getting a place to store files

If you want to use Refinery’s image and resource support, you need to add the ‘fog’ gem too. Edit the Gemfile as shown in Adding Amazon S3 Support below (you can do the other steps in that section after your site is first deployed).

3.2 Step 2: Configure the Puma web server

3.2.1 Create the Procfile

Create the Procfile in the root of your directory:

web: bundle exec puma -C config/puma.rb
3.2.2 Create the puma.rb config file

Create the puma config file in config/puma.rb +:

threads Integer(ENV['MIN_THREADS']  || 1), Integer(ENV['MAX_THREADS'] || 16)

workers Integer(ENV['PUMA_WORKERS'] || 3)

rackup DefaultRackup
port ENV['PORT'] || 3000
environment ENV['RACK_ENV'] || 'development'

on_worker_boot do
  # worker specific setup
  ActiveSupport.on_load(:active_record) do

3.3 Step 3: Set up asset precompilation

Inside config/environments/production.rb, Make sure that config.assets.compile is set to true add the following:

config.assets.compile = true

3.4 Step 4: Applying your changes

Now we just need to run bundle and add the changes to git:

bundle install
git add Gemfile
git add Gemfile.lock
git add Procfile
git add config/puma.rb
git commit -m "setup for Heroku"

3.5 Step 4: Set up your app on Heroku:

heroku create $app_name --stack cedar-14
git push heroku master

3.6 Step 6 (Option 1): Start from clean slate

If you haven’t set up anything locally, or don’t want to copy your local database to heroku, you’ll need to run a few commands to get Refinery’s database set up.

heroku run rake db:migrate
heroku run rake db:seed

This will set up the required database tables, and set up a homepage. Log in to your site to set up your first user.

heroku open

3.7 Step 6 (Option 2): Copy your data from your local database to the Heroku app

If you’ve developed your website locally, you likely have information in a local database that you would like to use. Rather than trying to recreate all that on Heroku, Heroku provides you with a task to push your local database to Heroku.

heroku pg:push

4 Adding Amazon S3 Support

If you want to use Refinery’s image and resource support you’ll need to setup storage, too. Heroku does not persist your app’s local filesystem, so to store uploaded files, you need to store them “in the cloud”. This section explains how to store the files in Amazon S3.

On Amazon S3, create a bucket called “my_app_production”. Then add this to the end of your Gemfile (this might already be done for you):

group :production do
  gem 'fog-aws'

Next, tell Heroku about your new S3 bucket.

heroku config:add S3_KEY=123key S3_SECRET=456secret S3_BUCKET=my_app_production

Make sure the config vars you add to Heroku match Refinery’s environment variables: S3_KEY, S3_SECRET, and S3_BUCKET

If you have created your bucket in a region other than us-east-1 you need to add S3_REGION also.

heroku config:add S3_REGION=s3region

That’s it! Heroku will restart your site and it should be live with S3 support.

5 Troubleshooting

5.1 Missing a required gem

Simply add that gem to the Gemfile.

5.2 Images or Resources don’t work

Double check your S3_ information and make sure that the right buckets actually exist. You can confirm against the values Heroku has recorded by running heroku config.

See the How to use Amazon S3 for storage guide for more specific information on file storage.

5.3 Other problems?

Otherwise, run heroku logs or heroku logs --tail and see if you can spot the error yourself. Or you could explore the help options available.