Craig Ambrose

Upgrading to Refinery CMS 2.0

Refinery 2.0 is out, and I certainly think it’s the best option for doing content management in Rails at the moment. It’s rails 3.2 compliant, uses the asset pipeline, and it’s all built using engines in the rails way.

Since the last stable release (1.0.8) however, Refinery has changed so much that there is no longer an official or automated upgrade path. An upgrade is possible however, and I’ll run you through the steps below. Your Refinery 1.0 app will of course be running on rails 3.0, and so upgrading you application also involves an upgrade of Rails at the same time. This article will assume that you already have some knowledge about upgrading from rails 3.0 to 3.2, but if not you can read plenty of great articles on that. Be sure to read up on the asset pipeline if you haven’t used it before.

Before you start, I also suggest that you create a sample Refinery 2.0 application to use as a reference. Perhaps even give it the same name as your real application, to help minimize the differences between your sample app and your real one if you wish to compare them in a file comparison tool.

This guide covers the main Refinery CMS engines. It doesn’t cover other commonly used engines, not even Blog or Search. What I’ve done is disabled those engines (comment the gems out in your Gemfile) for the upgrade, and then they can be re-enabled after the migration is complete. Leave me lots of love in the comments if you want me to post upgrade guides for those other engines.

Also, I’m sure I don’t even need to mention, do this upgrade in a branch.

STEP 1: Migrate Data

Refinery 2.0 does not know how to migrate your Refinery 1.0 database. You’ll need to manually insert a migration into your application and run it before you upgrade anything. I’ve written a migration, so go grab it here ( and paste it into a migration file in your app, then run it.

STEP 2: Upgrade Gems

Upgrade you Gemfile to rails 3.2.1 and Refinery 2.0. Comment out any other refinery engines temporarily.

STEP 3: Rails update

Perform the normal Rails 3.2 upgrade steps

  • Upgrade to a recent version of mysql2 if using an old mysql gem.
  • rake rails:update
  • Create assets dir, and move application images, stylesheets, javascripts

STEP 4: Upgrade refinery generated files

Run the refinery generator. This is normally done on a new app, but like rails:update will ask if you want to overwrite files. You’ll need to go through them one-by-one.

rails generate refinery:cms

In particular I found I had to ensure that I replaced: Refinery.rescue_not_found = false with Refinery::Core.rescue_not_found = false

STEP 5: Refresh cookies

Refresh your browser cookies. This is necessary if you have run the old version of the site in that browser. I imagine that this might also cause problems in a production deploy for users who still have their browser open.

STEP 6: Change partial paths

If you have overridden your application layout, you may have partial tags like like:

<%= render :partial => "/shared/html_tag" %>

Change to something like the following:

<%= render '/refinery/html_tag' %>

You many need to consult the application layout template inside refinery.

STEP 7: Move settings into config files

Move settings out of database. Settings now go in initializer files. Copy the entire config/initializers/refinery directory out of a sample refinery 2.0 app into your application, and go through and fill out the settings. Use the settings table in your database as a guide, but some settings have changed, so read the new initializer files right through.

STEP 8: Move overridden Refinery templates

For any templates you have overridden, they are probably now in the wrong paths. In particular, most are namespaced inside a refinery folder now. Consult the refiney codebase to find the new location of the overridden template. For example, /layouts/_header is now /refinery/header. Simply move the file in your application into a folder called “refinery” in your views folder.

STEP 9: Change custom template code

In your custom templates, you will need to update any code calling now invalid refinery APIs. In particular, calls to settings will now be invalid. For example, replace:

RefinerySetting.find_or_set(:site_name, "Company Name")



Likewise, all refinery routes are now namespaced. Replace root_path with refinery.root_path.

STEP 10: Create page slugs.

Refinery now uses friendly ID. These “slugs” are created for each page object on save. Create slugs for all pages by re-saving them all.

STEP 11: Profit!

You should be good to go now. Let me know how it went. :)