# Alchemy CMS: a Rails engine for component-based sites that also works headless

> Alchemy is a BSD-3 Rails CMS engine built on the idea that content should be separate from markup, with page versioning, multi-language and multi-domain support and a RESTful API that lets the same installation serve as a classic server-rendered site or a headless CMS. It is a Rails engine, so it lives inside your application rather than beside it.

**AlchemyCMS/alchemy_cms** — Alchemy is the Open Source Rails CMS framework for the component based web that can be used as classic server side rendered or headless CMS.

- Repository: https://github.com/AlchemyCMS/alchemy_cms
- Website: https://www.alchemy-cms.com
- Stars: 905 · Forks: 324
- Language: Ruby
- License: BSD-3-Clause
- Published: 2026-10-20 · Updated: 2026-10-20 · Language: en
- Canonical page: https://hysenlabs.com/projects/alchemycms-alchemy-cms

## A component model where the page is assembled, not filled in

Alchemy is described as an open source CMS engine written in Ruby on Rails, and the first feature in the list is flexible templating that separates content from markup. That single idea drives most of what follows. In a traditional CMS the editor picks a page and fills a set of fields, and the template decides what to do with them. In Alchemy the editor assembles a page from components, each of which is a self-contained unit with its own fields and its own rendering, and the layout is described separately. The practical effect is that a page is a tree of components rather than a record with columns, which is what makes features like page versioning, resource-oriented admin screens and the separation between content and markup possible rather than bolted on. It is also the reason Alchemy describes itself as a CMS framework rather than a CMS application, since the component set is meant to be extended.

## Headless and server-rendered from the same content model

The repository description calls Alchemy the open source Rails CMS framework for the component based web that can be used as classic server side rendered or headless CMS, and the feature list includes a rich RESTful API. This is the part that matters for a modern front end. Because the content model is a component tree rather than a template, it can be exposed as structured JSON through the API and consumed by a JavaScript front end, while the same tree renders server-side for a classic site. You are not running two systems and syncing them; you are choosing which presentation layer consumes the same data. The API is described as RESTful and the admin interface as resourceful, which is the vocabulary of a Rails engine that treats content as resources. The trade-off is that the headless path is only as good as the API's coverage, and the README does not document the API surface at all, so anyone planning a headless-first build needs to read the guides and the source rather than the feature list.

## Page versioning, multi-domain and multi-language, all in the engine

Three features stand apart from the basics because they are the ones a content team will actually miss if they are absent. Page versioning means an editor can see and restore earlier states of a page, which matters the moment more than one person can edit the same content. Multi language and multi domain means one installation can serve several locales and several hostnames with content organised accordingly, which is the shape of a site group rather than a single brand. User Access Control and the built-in contact form mailer cover the two other everyday needs, and the admin interface is described as intuitive with live preview, which is what lets an editor judge a layout before publishing it. Attachments and downloads, on-the-fly image cropping and resizing, and SEO friendly urls complete a list that reads like a checklist of what a content editor asks for.

## It is a Rails engine, so the host application is part of the product

The feature list says Alchemy is extendable via Rails engines and integrates into existing Rails apps, and the repository topics call it a rails-engine. That framing has consequences. Alchemy is not a separate service you point a browser at; it is a gem inside an application, mounted into routes, with its own models, controllers and admin screens, and its own migrations. The admin interface is described as a resourceful Rails admin, and the repository carries app, api, config, db, lib and spec directories alongside a Gemfile, so the engine and the host application live in one codebase. The consequence for a team is that Alchemy and your own Rails code share a process, a database and a deployment. That is the appeal, since an editor's changes flow straight into the same models your application reads, and it is the cost, since an upgrade of Alchemy is an upgrade of your application.

## ImageMagick and a SQL database are the stated hosting requirements

The hosting requirement in the feature list is specific: hostable on any server that supports Ruby on Rails, a SQL Database and ImageMagick. ImageMagick is there because of the on-the-fly image cropping and resizing, and that is a real operational dependency, because it is an external binary with its own security history and its own resource limits on large images. The SQL database requirement is deliberately loose, which suits the engine model, but it means the database support matrix is something to confirm rather than assume. The docker-compose file in the repository shows how the project itself develops the engine, with a setup service that resolves the bundle fresh and installs JavaScript dependencies, and a web service that runs the dummy application inside the image. The comments in that file explain a detail worth borrowing: the image bakes gems and node_modules in, and an anonymous volume shadows the host's node_modules directory so the image's copy, with its platform-specific binaries, is used instead of the host's.

## Installing into an existing Rails app takes a bundle add and an initializer

There are two documented paths. If you have no Rails project yet, the README suggests a Rails template, and the commands are:

```bash
gem install rails
```

then

```bash
rails new -m https://raw.githubusercontent.com/AlchemyCMS/rails-templates/master/all.rb <MY-PROJECT-NAME>
```

For a manual install into an existing application, you add the gem:

```bash
bundle add alchemy_cms
```

Then you decide who owns authentication. Alchemy ships a Devise based user model, extracted into its own gem called alchemy-devise, which you add with bundle add alchemy-devise and then install with bin/rails g alchemy:devise:install. If you want your own user model instead, the README says to tell Alchemy about it through an initializer, with the configuration shown in the documentation:

```ruby
# config/initializers/alchemy.rb
Alchemy.configure do |config|
  config.user_class          = 'YourUserClass'          # This has to be configured
  config.current_user_method = 'current_admin_user'     # Defaults to 'current_user'
```

The user_class line has to be set; the current_user_method defaults to current_user.

## The main branch is a development branch, and each Rails line has its own stable branch

The README carries a caution at the top: this main branch is a development branch that can contain bugs, and for productive environments you should use the current Ruby gem version or the latest stable branch, 8.0-stable. The compatibility table is long and specific. This version runs with Rails 7.2 or newer, with a 7.1 compatible version on 8.0-stable, 7.0 on 7.4-stable, 6.1 on 7.0-stable, 6.0 on 6.1-stable, down to Rails 2.3 on 1.6-stable. On Ruby the table runs from Ruby 3.1 or later including 4.0 downwards. The practical reading is that Alchemy supports a wide range of Rails versions, but not simultaneously. Each Rails line gets its own maintained branch, so pinning means choosing the branch that matches your Rails version rather than tracking the newest code. There is also a propshaft note, since for Rails 8 or newer you need Alchemy 8.0.0a or later, and on an older Alchemy with Rails 8 you have to comment out the propshaft gem temporarily.

## A live demo with published credentials, and the wider Rails tooling around it

There is a demo instance at demo.alchemy-cms.com with the login demo and the password demo123 published in the README, which is the fastest way to see the component model and the admin interface without installing anything. The project is also backed by an open collective with backers and sponsors, and the main sponsor is Blish. The engineering signals in the repository are a good deal more informative than the feature list. There is a build and test workflow badge, a Brakeman scan workflow for static security analysis, a lint workflow, codecov for coverage, Depfu for dependency review, and a Code Climate configuration. The frontend is a separate concern with its own toolchain: the package manifest is named alchemy_admin, runs vitest for tests, prettier and eslint for linting, and rollup for the JavaScript builds, with sass compiling the admin stylesheets including several TinyMCE skins.

## Conclusion

Alchemy suits a Rails team that wants CMS authoring without leaving the Rails stack, and that needs the same content model to serve both server-rendered pages and a headless front end, with page versioning and multi-domain support already handled. It does not suit a non-Rails project, since it is a Rails engine and integrates into an existing application rather than standing alone, and it does not suit a team that wants the main branch, which the README marks as a development branch that can contain bugs. Before you adopt it, pin a released gem version or the 8.0-stable branch rather than tracking main, check that your Rails and Ruby versions match, and read the Rails version compatibility table before upgrading, because each Rails line has its own maintained Alchemy branch.

## FAQ

### How do I install Alchemy CMS into a Rails application?

Add the gem with bundle add alchemy_cms, then either add bundle add alchemy-devise and run bin/rails g alchemy:devise:install, or point Alchemy at your own user model through an initializer setting config.user_class and config.current_user_method.

### Which Rails and Ruby versions does Alchemy support?

This version runs with Rails 7.2 or newer and Ruby 3.1.0 or later including 4.0. Older Rails lines have their own stable branches, from 8.0-stable for Rails 7.1 down to 1.6-stable for Rails 2.3, and older Ruby versions map to branches such as 7.2-stable and 5.2-stable.

### Can Alchemy be used as a headless CMS?

Yes. The project describes itself as usable as a classic server side rendered site or as a headless CMS, with a rich RESTful API, and the component-based content model is what makes both paths work from the same data.

### Should I use the main branch of alchemy_cms in production?

The README states that the main branch is a development branch that can contain bugs, and points productive environments at the current Ruby gem version or the latest stable branch, 8.0-stable.

## Sources

- [AlchemyCMS/alchemy_cms on GitHub](https://github.com/AlchemyCMS/alchemy_cms)
- [License: BSD-3-Clause](https://github.com/AlchemyCMS/alchemy_cms/blob/main/LICENSE)
- [Project website](https://www.alchemy-cms.com)
- [README](https://github.com/AlchemyCMS/alchemy_cms/blob/main/README.md)
- [Releases](https://github.com/AlchemyCMS/alchemy_cms/releases)

---

Hysen Labs editorial analysis, written from the project's own repository and release notes. Cite the canonical page: https://hysenlabs.com/projects/alchemycms-alchemy-cms