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:
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.