ChaptersThis guide is based on Refinery CMS 2.0.0. Much of the code shown here will not work in earlier versions of Refinery.
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.
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 does a couple of things:
- creates config/initializers/refinery/ and copies over all the required initializers from Refinery
- copies all Refinery migrations to your apps migration folder and runs these migrations, and adds the seed data to your database
- injects Refinery’s mounting line into your config/routes.rb file
- inserts require refinery/formatting and require refinery/theme lines in your apps application.css file
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.