# Refinery CMS: a Rails-native CMS for client-editable sites > Refinery CMS is an MIT-licensed Ruby on Rails engine that gives non-technical clients a page editor while keeping developers inside standard Rails views, controllers and migrations. This review covers what it installs onto, how extensions work, and where it stops being the right choice. **refinery/refinerycms** — An extendable Ruby on Rails CMS that supports Rails 6.1 to 8.1+ and Ruby 3.x to 4.x - Repository: https://github.com/refinery/refinerycms - Website: https://github.com/refinery/refinerycms - Stars: 3,905 · Forks: 1,223 - Language: Ruby - License: MIT - Published: 2026-09-23 · Updated: 2026-09-23 · Language: en - Canonical page: https://hysenlabs.com/projects/refinery-refinerycms ## The problem Refinery CMS solves: clients editing their own pages Most Rails applications have no content model at all. Marketing copy lives in a view, a phone number lives in a partial, and every text change becomes a deploy. Refinery CMS is aimed at the case where that is unacceptable: the README says it is "great for sites where the client needs to be able to update their website themselves without being bombarded with anything too complicated." That sentence is the whole product thesis. The audience is a Rails developer building a brochure site, a small news site, or an internal portal for an organisation that has a communications person rather than an engineering team. The second audience is the developer. Refinery does not ask you to learn a new templating language or a plugin format invented for the CMS. Pages, images, files and users are Rails models, and the admin is a Rails engine mounted into your application. If you already know where a controller goes in a Rails app, you know where a Refinery controller goes. That is a deliberate constraint, and it is the reason the project has stayed legible to Rails developers rather than growing its own DSL. ## Pages, Dragonfly attachments and Devise users: the actual architecture Refinery ships as a set of Rails engines, not a standalone server. The repository is organised around that: core/ holds the main engine, pages/, images/, resources/ and dragonfly/ are separate top-level directories, and each can be pulled in or left out. When you run the installer, the engines mount into your application's routes and the admin becomes a path inside your own app. The feature set maps onto that layout. Pages are a tree you manage from the admin, with a visual editor for the body. Images and files are stored through Dragonfly, and the README states that storage on Amazon S3 is supported, so the attachment backend is a configuration decision rather than something baked into the schema. Authentication and authorisation come from Devise, with per-user control over which extensions a user can reach. That last point matters for multi-editor sites: you can give one person the blog and another the page tree without writing your own permission layer. Extensions are the extension mechanism. The README points at rails generate refinery:engine as the way to build one, and lists Blog, Portfolio, News and Inquiries as popular examples maintained as separate repositories. Because each extension is itself a Rails engine, the boundary between "Refinery feature" and "your feature" is a gem boundary. That is a clean design, but it also means the quality of your site depends partly on code outside this repository. ## Installing Refinery CMS with the Rails template Refinery is not installed by adding a gem to an existing Gemfile and running bundle install. The documented route is a Rails application template, applied at the moment you create the app. The README gives this command for Rails 5.1+ support using version 4.0.x: ```bash rails new app_name -m https://www.refinerycms.com/t/4.0.0 ``` The template fetches Refinery and wires it into the generated application. The README also documents a 3.0.x template for Rails 4.2.x and an edge template for the latest code. Note the gap: the README's own template examples name Rails 5.1 and 4.2, while the project description says Rails 6.1 through 8.1+ is supported. The README itself warns that "some of our docs in this README are out of date" and directs readers to the repository and the doc/guides folder. Treat the guides, not the README's template URLs, as the authority for your Rails version. Two prerequisites are non-negotiable. Bundler must be present, and so must ImageMagick, because image processing depends on it. The README carries a warning that ImageMagick has a serious security vulnerability, CVE-2016-3714, and that after installing you must disable certain features in ImageMagick's policy configuration, linking to imagetragick.com for the details. On macOS the README suggests brew install imagemagick. Do not skip the policy step on a public server. Once the app exists, extensions are generated rather than hand-written. The README gives this command and notes that running it without options prints help: ```bash rails generate refinery:engine ``` What you should see is a scaffolded engine directory inside your application, ready to be edited like any other Rails engine. The admin itself is reachable after the template finishes; the Getting Started guide under doc/guides is where the project sends new users for the walkthrough. ## Where Refinery CMS is the wrong tool The README is unusually candid about documentation drift: it states that some docs are out of date and that the project website is not currently live. For an engineer evaluating a CMS, that is a real cost. You will be reading guides in the repository and checking them against your Rails version rather than following a maintained manual. If your team needs a documented upgrade path with release notes per version, this is friction you will feel on every Rails upgrade. The ImageMagick dependency is the second constraint, and it is not cosmetic. The README instructs you to disable features in ImageMagick's policy configuration after installing because of CVE-2016-3714. That is an operational task on every host, including containers and CI, and it is the kind of thing that gets missed when a build image is rebuilt. If your deployment environment cannot carry a hardened ImageMagick with a custom policy file, Refinery is the wrong choice regardless of how well the CMS itself fits. The third case is a team with no Rails. Refinery's advantages come from being a Rails engine: standard views, standard migrations, standard gems. If nobody on the team writes Ruby, those advantages invert into a maintenance burden, and a hosted CMS or a static site generator will be cheaper to own. ## Refinery CMS versus a self-contained CMS such as WordPress The honest comparison is with WordPress, because both target the same buyer: an organisation whose staff edit their own content. The difference is architectural. WordPress is a PHP application you host and extend through plugins and themes, and it brings its own runtime, its own database conventions and its own admin. Refinery is a library inside your Rails application. There is no separate application to patch, because the CMS is a set of gems in your Gemfile. That changes who can extend it. A WordPress plugin can be installed by a non-developer from an admin screen. A Refinery extension is a Rails engine you generate with rails generate refinery:engine and then write yourself, or pull in as a gem. The README lists Blog, Portfolio, News and Inquiries as popular extensions, but they are repositories, not one-click installs. The trade is real: you get a codebase that behaves like the rest of your application, and you give up the plugin marketplace model that makes WordPress approachable for non-programmers. A second difference is the content model. WordPress is built around posts and a theme hierarchy. Refinery is built around a page tree with a visual editor, with blogging, news and portfolios added as extensions. If your site is fundamentally a blog, the extension route adds a layer that WordPress gives you by default. If your site is a set of pages a client edits, the page tree is the more direct fit. ## Maintenance, licensing and what an upgrade actually costs The repository is not archived, and the last push was on 2026-05-11. The most recent releases listed are v4.1.0 and 4.0.3, both dated 2026-05-11. That is a recent release, so the project is being published to, but the README's own admission of stale documentation means you should budget time for reading source and guides rather than trusting a changelog to describe every breaking change. The changelog.md file at the repository root is the place to start for a version jump. The upgrade surface is larger than a single gem's. Refinery is a set of engines, and the extensions you use are separate repositories with their own release cycles. A Rails upgrade therefore has to move the core, the extension gems and your own generated engines together. The README's supported range, Rails 6.1 through 8.1+ and Ruby 3.x through 4.x, tells you the maintainers track Rails releases, but it does not tell you that a given extension has been updated for the newest Rails. Check each extension repository before you plan the upgrade. Licensing is straightforward. Refinery CMS is released under the MIT license, and the README points to license.md for the text. MIT is permissive: it allows commercial use and modification, and it requires that the copyright notice and permission notice travel with copies. That is a summary, not legal advice. If you redistribute a modified Refinery as part of a product, read license.md and your own counsel's guidance. Note also that the extensions are separate repositories, so their licenses are their own and should be checked individually rather than assumed to match the core. ## Conclusion Adopt Refinery CMS when the client's own staff must edit pages and your team already writes Rails: the generator, Devise-backed users and Dragonfly attachments keep everything inside a normal Rails app. Do not adopt it when you need a hosted admin, a documented upgrade path, or a stack without ImageMagick. Before committing, check the doc/guides folder against your Rails version, confirm the ImageMagick policy file referenced by imagetragick.com is in place, and run rails generate refinery:engine once to see whether the generated extension matches the structure your app expects. ## FAQ ### What is Refinery CMS? Refinery CMS is an open source content management system built as a set of Ruby on Rails engines. The README describes it as aimed at end users, for sites where the client needs to update the website themselves, and it is released under the MIT license. ### Which Rails and Ruby versions does Refinery CMS support? The project description states Rails 6.1 to 8.1+ and Ruby 3.x to 4.x. The README's own install templates name older versions, and it warns that parts of the README are out of date, so check the guides in doc/guides for your version. ### How do I install Refinery CMS? The documented route is a Rails application template, for example rails new app_name -m https://www.refinerycms.com/t/4.0.0 for version 4.0.x. Bundler and ImageMagick are listed as requirements, and the README warns that ImageMagick's policy configuration must be adjusted after installing. ### Does Refinery CMS need ImageMagick? Yes. ImageMagick is listed under Requirements, and the README warns about CVE-2016-3714, instructing you to disable certain features in ImageMagick's policy configuration after installing and pointing to imagetragick.com for details. ### How do I add a custom feature to Refinery CMS? The README says to run rails generate refinery:engine, and notes that running the command without options prints help. Extensions such as Blog, Portfolio, News and Inquiries are maintained as separate repositories. ## Sources - [License: MIT](https://github.com/refinery/refinerycms/blob/main/LICENSE) - [Project website](https://github.com/refinery/refinerycms) - [README](https://github.com/refinery/refinerycms/blob/main/README.md) - [refinery/refinerycms on GitHub](https://github.com/refinery/refinerycms) - [Releases](https://github.com/refinery/refinerycms/releases) --- Hysen Labs editorial analysis, written from the project's own repository and release notes. Cite the canonical page: https://hysenlabs.com/projects/refinery-refinerycms