Using Refinery with an Existing Rails App

This guide covers integration with Refinery CMS. After reading it, you should be familiar with:

  • Attaching Refinery CMS to an existing Rails application
Edit this guide on Github

This guide is based on Refinery CMS 2.0.×. Much of the code shown here will not work in earlier versions of Refinery.

Refinery CMS 2.0.x has a minimum requirement of Rails 3.1.3

1 Guide Assumptions

This guide is designed for those who want to attach Refinery CMS to an existing Rails application. It assumes you have at least introductory knowledge of Refinery CMS.

2 Steps to add Refinery CMS to your application

Refinery now comes as a mountable Rails extension. This is a change from previous versions, where Refinery would have to modify files in your application. Now, Refinery is completely namespaced and isolated from your existing application.

2.1 Add Refinery CMS as a dependency in your Gemfile

Open up your Gemfile and add the latest version (a later version than the one shown may exist):

gem 'refinerycms', '~> 2.0.0'

Now, to install the gem, run:

bundle install

2.2 Generate support files and migrations, and prepare the database

Doing this will overwrite any tables that you have of the same name; please backup first. Refinery table names begin with refinery_, so the likelihood of a collision occurring is low, but it is nevertheless recommended you keep backups of your database and your code.

Running the bundle exec rake railties:install:migrations task will copy migrations from any Rails extension you have listed in your Gemfile. It is recommended that you only install one extension at a time to prevent a massive influx of migrations that may conflict with each other. This will not overwrite any existing migrations you have, though, so you can run this command more than once without fear.

Generating Refinery on top of an existing application is marginally more complicated than it was before, but it’s still quite simple:

rails generate refinery:cms --fresh-installation

This creates config/initializers/refinery/ and copies over all the required initializers from Refinery and Devise. It also injects Refinery’s mounting line into your config/routes.rb file. If you wish to customize where Refinery is mounted, you can change the path there.

2.3 Migrate and seed the database.

bundle exec rake railties:install:migrations
  bundle exec rake db:migrate
  bundle exec rake db:seed

This copies the migrations from Refinery, migrates them, and adds the seed data to your database to provide you with the minimal Refinery installation.

After this, you should be all set. Don’t forget to revisit the initializers in config/initializers/refinery/ to customize your experience.

3 Getting Help

As this is a relatively new process, if you need help with any of these steps we would love to hear about it.