Comfy Middle Seat
A self-hosted, embeddable CMS engine for Rails 7.2+, 8.x
Add editor-managed pages, reusable layouts, rich text, Markdown, files, translations, search, and revision history to an existing Rails application—without moving your content into a separate service.
Comfy Middle Seat is actively maintained and continues the lineage of Comfortable Mexican Sofa and Comfortable Media Surfer. It keeps the memorable C.M.S. initials, with a new place to sit. It all depends on who is sitting to your right and left.
Quick Start · Features · Documentation · Upgrading · Contributing
Why Comfy Middle Seat?
Choose Comfy Middle Seat when you want content editing inside your Rails application rather than a separate hosted CMS.
- Keep application code and CMS-rendered pages together.
- Own and host your content, database, and files.
- Use familiar Rails controllers, views, helpers, authentication, and authorization.
- Add CMS-managed pages without creating a separate frontend application.
- Extend or override the admin area using normal Rails conventions.
Comfy Middle Seat is best suited to Rails applications that render their own websites. It is not intended to be a hosted SaaS CMS or a JavaScript-first visual page builder.
Features
For content editors
- Hierarchical pages with fast, on-demand tree navigation.
- Rich text, Markdown, plain text, images, files, dates, numbers, checkboxes, and reusable snippets.
- Search across page titles, paths, and content.
- Searchable image and file selection inside the editor.
- Local draft recovery for Pages and Translations.
- Revision history with comparison, preview, and restore workflows.
- Page translations and multilingual publishing.
- Multi-site publishing from one installation.
- Publish individual pages or whole branches, with ancestor-aware visibility.
For Rails developers
- Drop-in Rails engine with configurable admin and public routes.
- Flexible layouts built with simple
{{ cms:... }}content tags. - Active Storage integration for files and images.
- CMS seed files for version-controlled starter content.
- Configurable authentication and authorization.
- Extendable admin views, controllers, helpers, and partials.
- Stable
comfy_cms_*database tables for upgrades from Sofa and Surfer. - CI coverage across current Ruby and Rails releases.
Rails compatibility and security
Rails 7.2 remains compatibility-tested, with tests, lint, and Brakeman required in CI. Its dependency audit is temporarily advisory-only because current security findings have no patched 7.2 release; failures remain visible in CI logs, warnings, and job summaries. Dependency audits remain required on Rails 8.0 and 8.1. Use a Rails release patched for current advisories in production; passing compatibility tests is not a security guarantee.
Quick Start
Add the gem to your Rails application's Gemfile:
gem "comfy_middle_seat", "~> 4.0"Install the gem and generate the CMS:
bundle install
bin/rails active_storage:install
bin/rails generate comfy:cms
bin/rails db:migrate
bin/rails comfy:compile_assetsThe generator adds the CMS routes and creates config/initializers/comfy_middle_seat.rb.
Make sure the public content route remains after your application's other routes so it does not capture them first:
comfy_route :cms_admin, path: "/admin"
comfy_route :cms, path: "/"Start Rails and open http://localhost:3000/admin. The generated development credentials are user and pass.
Security: Replace the default admin credentials or configure application authentication before exposing the admin area to a network.
Basic configuration
Use the ComfyMiddleSeat namespace in config/initializers/comfy_middle_seat.rb:
ComfyMiddleSeat.configure do |config|
config.cms_title = "My CMS"
config.admin_base_controller = "ApplicationController"
end
ComfyMiddleSeat::AccessControl::AdminAuthentication.username = "admin-user"
ComfyMiddleSeat::AccessControl::AdminAuthentication.password = "change-me"The initializer documents additional options for authentication, authorization, revisions, locales, seeds, helpers, partials, and application integration.
How content works
A Site defines a hostname, path, and language. Layouts define page structure and the fields editors can manage. For example:
<div id="page">
{{ cms:snippet header }}
<div id="main">
<div id="content">
{{ cms:breadcrumbs }}
{{ cms:siblings exclude: "search,comments" }}
<hr/>
{{ cms:markdown content }}
</div>
</div>
</div>When an editor creates a Page using this Layout, the admin automatically presents fields for title and content. Content tags can also provide Markdown, files, images, dates, numbers, checkboxes, snippets, partials, helpers, navigation, and other reusable content.
Descriptive tag aliases
These names are interchangeable; existing tags remain supported:
| Existing tag | Alias |
|---|---|
asset |
layout_asset |
partial |
render_partial |
template |
render_template |
{{ cms:layout_asset main, type: css, as: tag }}
{{ cms:render_partial "layouts/embed_video", id: MYpbvXgpIzc }}
{{ cms:render_template "marketing/landing" }}Aliases preserve all parameters, defaults, and existing allowlist behavior. No new allowlist requirement or content migration is introduced. Asset tags still require type: css or type: js; omitting the type does not default to CSS. Their URLs follow the configured Rails routes, not an independent manual override of public_cms_path. HTML attributes are preserved, though formatting may differ. Check for conflicts if your application already registers custom tags with these alias names.
Tag usage audit
Open Tag usage in the admin navigation to list unique partials, helpers, and templates for the selected site. Expand Used in for source edit links. The report shows current permissions and candidate allowlists for review; it does not change permissions.
For an application-wide inventory, use the Rake task:
bin/rails comfy:cms:tag_usage
bin/rails comfy:cms:tag_usage SITE=default
bin/rails comfy:cms:tag_usage FORMAT=json
bin/rails comfy:cms:tag_usage FORMAT=configSITE is a site identifier, not its numeric ID; omit it to scan all sites. FORMAT defaults to text. JSON includes source locations, scope, permissions, and warnings. Configuration output is a copyable initializer block. Both options can be combined.
The scanner reads saved layouts, snippets, page fragments, and translation fragments, including unpublished content. Aliases share one entry; counts refer to distinct source fields, not runtime executions. CMS comments are excluded. No helpers, views, ERB, or pages are executed, and caches are not read or updated.
Review before applying candidate allowlists. Discovered names—including currently blocked names—are not automatically safe. Allowlists are application-wide, so a single-site report is not sufficient for a multi-site installation. Replacing an allowlist blocks omitted names, including previously approved ones.
Warnings identify malformed comments or parameters. They go to stderr, and an incomplete scan exits nonzero while still emitting the partial report. JSON includes the warnings too; generated configuration marks incomplete scans. Unknown sites and unsupported formats also exit nonzero.
This is a source inventory, not runtime dependency analysis. It does not scan revisions, unsaved drafts, unimported seed files, layout CSS/JavaScript, application views, or dynamically generated tags. Restoring revisions or importing content can introduce new names; scan again afterward. Concurrent content edits are not a database snapshot, so rescan before changing permissions.
Editor shortcuts
In HTML and Markdown code editors, type a shortcut and press Tab to insert a CMS tag. The parameter placeholder is selected so you can replace it immediately. For example, ;md inserts {{ cms:markdown content }} with content selected.
Type ;; then Tab, or press Ctrl+Space, for a searchable shortcut list. Search by shortcut or tag name: c prioritizes comment, children, and other c shortcuts; p fl finds page_file_link. Exact and prefix matches appear before fuzzy matches.
Use the arrow keys and Enter or Tab to choose. The tag replaces the entire trigger and search text. Escape closes the list without changing your text. Full names such as ;markdown also work for direct expansion. One Undo reverses the expansion without removing what you typed.
| Shortcut | Inserts | Selected placeholder |
|---|---|---|
;md |
markdown |
content |
;tx |
text |
field |
;ta |
textarea |
content |
;wys |
wysiwyg |
content |
;da |
date |
field |
;dt |
datetime |
field |
;num |
number |
field |
;cb |
checkbox |
field |
;fi |
file, as a link |
attachment |
;fs |
files, as links |
attachments |
;im |
image |
image label |
;au |
audio |
path/to/audio |
;fl |
file_link, as a link |
file_id |
;pfl |
page_file_link, as a link |
attachment |
;sn |
snippet |
identifier |
;as, ;css
|
CSS asset tag |
layout_identifier |
;js |
JavaScript asset tag |
layout_identifier |
;hlp |
helper |
method_name |
;par |
partial |
path/to/partial |
;tpl |
template |
path/to/template |
;cr |
breadcrumbs |
— |
;ch |
children |
— |
;si |
siblings |
— |
;com |
Complete multiline comment block | Comment here |
;nt |
comment "Note" (also ;note) |
Note |
;ec |
endcomment |
— |
;end |
end |
— |
Placeholders are examples: replace them with your field names, identifiers, paths, or IDs. ;asset inserts the CSS version; ;comment inserts a full comment block. The descriptive aliases (;layout_asset, ;render_partial, ;render_template) also work for expansion and search, inserting the existing tag spellings.
Shortcuts work at the start of a line, after whitespace, or after >, outside an existing CMS tag. Unrecognized shortcuts retain normal Tab behavior. CSS, JavaScript, ordinary text fields, and visual editors are unchanged. Saved content uses the standard {{ cms:... }} syntax.
CMS comments
Use a quoted note for a short comment:
{{cms:comment "Replace this banner in December"}}Use a block to hide a section, including any CMS tags inside it:
{{cms:comment}}
Internal note: this section is not ready.
{{cms:markdown old_content}}
{{cms:snippet seasonal_banner}}
{{cms:endcomment}}Comments produce no rendered output and do not create editor fields. Unlike HTML comments, enclosed CMS tags are not processed. Source text and existing field values remain stored; removing a comment restores normal processing.
Blocks may be nested and must end with {{cms:endcomment}}, not {{cms:end}}. Short notes accept single or double quotes, with backslash-escaped quotes. Unclosed blocks and malformed comment tags raise a clear syntax error. Comments work in layouts, snippets, and rendered fragment content, including Markdown. They are not a place for secrets: original source remains available to editors and may be exposed by APIs that include raw content.
Image resizing
Resize images from the media library or page attachments without changing the originals:
{{ cms:image "Homepage banner", resize_to_limit: "1600x600" }}
{{ cms:file card_photo, as: image, resize_to_fill: "600x400" }}
{{ cms:image "Product photo", resize_and_pad: "500x500" }}The same options work with file, files, image, file_link, and page_file_link:
| Option | Result |
|---|---|
resize_to_limit |
Fit within the dimensions; never enlarge. |
resize_to_fit |
Fit within the dimensions; allow enlargement. |
resize_to_fill |
Fill the exact dimensions with a centered crop. |
resize_and_pad |
Fit the whole image into the exact dimensions with padding. |
Specify one operation and positive dimensions as "WIDTHxHEIGHT". Invalid values, conflicting operations, and dimensions above the configured limit raise an error. Padding uses the processor's defaults; its color/transparency can differ between processors and image formats. Sizing options are ignored for missing attachments and files that Active Storage cannot transform, such as PDFs and SVGs under its default configuration. Missing attachments render nothing; non-transformable files retain their original URLs.
The default maximum requested width or height is 4096 pixels. Change it in config/initializers/comfy_middle_seat.rb:
ComfyMiddleSeat.configure do |config|
config.max_image_dimension = 6000
endThis limits requested tag dimensions, not upload sizes or all intermediate processing memory. Admin thumbnails use fixed sizes.
The CMS respects your application's Active Storage processor. Use ImageMagick with :mini_magick, or install libvips and add ruby-vips to your application's Gemfile, then configure:
# config/application.rb, inside your application class
config.active_storage.variant_processor = :vipsRestart after changing processors. No processor switch is required to use the new options; the gem retains its existing MiniMagick dependency for compatibility.
Existing image tags
-
resize: "400x300"translates toresize_to_fit;resize: "400x300>"translates toresize_to_limit. Both work with either processor. - Supported legacy combinations of
resize,gravity, andcropretain their operation order under MiniMagick. Resize acceptsWxHwith an optional>,<,!, or^suffix; crop requiresWxH+X+Y(signed offsets). Offset-free crops are rejected because ImageMagick treats them as tiling, not a single crop. Gravity accepts the standard compass positions andcenter. - Other legacy geometry, including percentages and one-dimensional sizes, raises an actionable error. Replace it with an explicit two-dimensional operation. The size limit applies to legacy dimensions too.
- Complex legacy expressions are not silently approximated on Vips. Convert them before switching processors; do not mix legacy and modern options in a tag.
After upgrading, clear rendered page and translation caches once so image links use the new transformations:
Comfy::Cms::Page.update_all(content_cache: nil)
Comfy::Cms::Translation.update_all(content_cache: nil)No database migration or re-upload is needed. New variants are generated on demand and may increase storage use temporarily; originals and old variants are not deleted. Purge any external page/CDN HTML caches separately. Clear rendered caches again after changing the sizing policy. Active Storage's variant keys do not include the processor: switching processors reuses existing variants with the same options, even after clearing page caches. To regenerate those images with the new processor, invalidate the affected derived variants separately, preserving the original uploads, and clear any cached derivative files on your CDN.
Publishing pages
A page is publicly visible only when it and all its ancestors are published. Unpublishing a parent hides its branch without changing descendants’ individual publication settings. Republishing the parent restores only descendants whose full ancestor chain is published; drafts stay unpublished. Translations must also satisfy their own publication settings.
The Page index toggle changes only that page. The Child pages menu’s Publish descendants and Unpublish descendants actions change all descendants, not the current page or its ancestors. The admin marks published pages hidden by an unpublished ancestor.
Development mode continues to show unpublished pages for preview. Check public visibility in test, staging, or production mode.
Compatibility and requirements
| Component | Support |
|---|---|
| Ruby | 3.2 or newer; CI tests 3.3, 3.4, and 4.0 |
| Rails | CI tests 7.2, 8.0, and 8.1 |
| Node.js | 18 or newer for asset compilation |
| File storage | Active Storage |
| Image processing | ImageMagick or libvips (via Active Storage) |
Pagination is provided by Kaminari. The admin uses Bootstrap, CodeMirror, and Redactor.
Documentation
The Comfortable Media Surfer Wiki remains a reference for inherited CMS features while first-party Comfy Middle Seat documentation is expanded.
Useful starting points:
When adapting upstream examples, use the comfy_middle_seat gem, config/initializers/comfy_middle_seat.rb, and the ComfyMiddleSeat Ruby namespace.
Upgrading
File-link and image escaping (unreleased)
File links and images now escape labels and HTML attributes. Labels containing HTML display as text; URLs, labels, image titles, CSS classes, and file separators otherwise retain their existing behavior. Links opening a new tab include rel="noopener".
Clear rendered page and translation caches once after deployment so existing pages use the escaped markup:
Comfy::Cms::Page.update_all(content_cache: nil)
Comfy::Cms::Translation.update_all(content_cache: nil)Content regenerates on demand. No database migration is required. Helper, partial, and template permission defaults are unchanged; the new Tag usage audit is read-only.
Ancestor-aware publishing (unreleased)
Review branches with unpublished ancestors: their descendants will no longer be publicly accessible. No database migration is required. After deploying, clear existing rendered content once from the Rails console so cached navigation follows the new rule:
Comfy::Cms::Page.update_all(content_cache: nil)
Comfy::Cms::Translation.update_all(content_cache: nil)Content is regenerated on demand. Subsequent publication and parent changes refresh the affected site’s caches automatically.
From Comfortable Media Surfer
-
Replace
comfortable_media_surferwithcomfy_middle_seatin theGemfile. Do not include both gems. -
Run
bundle install. -
Preview and run the standalone initializer converter from the Rails application root:
bundle exec comfy-middle-seat-upgrade --dry-run bundle exec comfy-middle-seat-upgrade
-
Replace any remaining Ruby references from
ComfortableMediaSurfertoComfyMiddleSeat.
The converter renames config/initializers/comfortable_media_surfer.rb to config/initializers/comfy_middle_seat.rb, updates namespace references, and preserves the original as a .bak file. It refuses to overwrite an existing initializer or backup.
The existing comfy_cms_* tables, schema, and stored records are used as-is. No CMS database migration is required for this upgrade.
From Comfortable Mexican Sofa
Upgrade the application to Rails 7.2 or newer, replace the old gem with comfy_middle_seat, run bundle install, generate or convert config/initializers/comfy_middle_seat.rb, and update application integrations to use ComfyMiddleSeat.
Sofa and Comfy Middle Seat use the same comfy_cms_* database table names, so the CMS tables do not need to be renamed.
From Occams
Upgrade the application to Rails 7.2 or newer and replace Occams with comfy_middle_seat. Occams used different table names and namespace values, so its data requires conversion:
ALTER TABLE occams_cms_categories RENAME TO comfy_cms_categories;
ALTER TABLE occams_cms_categorizations RENAME TO comfy_cms_categorizations;
ALTER TABLE occams_cms_files RENAME TO comfy_cms_files;
ALTER TABLE occams_cms_fragments RENAME TO comfy_cms_fragments;
ALTER TABLE occams_cms_layouts RENAME TO comfy_cms_layouts;
ALTER TABLE occams_cms_pages RENAME TO comfy_cms_pages;
ALTER TABLE occams_cms_revisions RENAME TO comfy_cms_revisions;
ALTER TABLE occams_cms_sites RENAME TO comfy_cms_sites;
ALTER TABLE occams_cms_snippets RENAME TO comfy_cms_snippets;
ALTER TABLE occams_cms_translations RENAME TO comfy_cms_translations;
UPDATE comfy_cms_categories SET categorized_type = 'Comfy::Cms::Page' WHERE categorized_type = 'Occams::Cms::Page';
UPDATE comfy_cms_categorizations SET categorized_type = 'Comfy::Cms::Page' WHERE categorized_type = 'Occams::Cms::Page';
UPDATE comfy_cms_fragments SET record_type = 'Comfy::Cms::Page' WHERE record_type = 'Occams::Cms::Page';
UPDATE comfy_cms_fragments SET record_type = 'Comfy::Cms::Layout' WHERE record_type = 'Occams::Cms::Layout';
UPDATE comfy_cms_fragments SET record_type = 'Comfy::Cms::Snippet' WHERE record_type = 'Occams::Cms::Snippet';
UPDATE comfy_cms_revisions SET record_type = 'Comfy::Cms::Page' WHERE record_type = 'Occams::Cms::Page';
UPDATE comfy_cms_revisions SET record_type = 'Comfy::Cms::Layout' WHERE record_type = 'Occams::Cms::Layout';
UPDATE comfy_cms_revisions SET record_type = 'Comfy::Cms::Snippet' WHERE record_type = 'Occams::Cms::Snippet';
UPDATE active_storage_attachments SET record_type = 'Comfy::Cms::File' WHERE record_type = 'Occams::Cms::File';Back up the database and test this conversion outside production first.
Project history
- Comfortable Mexican Sofa, created by Oleg Khabarov, established the original Rails CMS.
- oCcaMS explored a revival after Sofa became inactive.
- Comfortable Media Surfer, sponsored by ShakaCode, brought the project forward for current Rails versions.
- Comfy Middle Seat continues that work under its own namespace, release line, and maintenance direction.
See the Changelog, Sofa releases, and Surfer releases for the complete inherited history.
Add-ons
For blog functionality, see ComfyBlog.
Contributing
Contributions are welcome. See CONTRIBUTING.md for setup and pull-request guidance.
The main checks are:
bundle exec rake test
bundle exec rails test:system
bundle exec rubocopBug reports and focused feature proposals can be opened through GitHub Issues.
Acknowledgements
- Oleg Khabarov and the contributors to Comfortable Mexican Sofa, the original Comfy CMS. Recent improvements also draw on Oleg’s ongoing Sofa 3.0 work, selectively adapted to preserve compatibility.
- Andrew vonderLuft for reviving Sofa with the oCcaMS project, and carrying it forward.
- ShakaCode for sponsoring the revived project as Comfortable Media Surfer.
- Roman Almeida for contributing the OEM license for Redactor Text Editor.
Copyright 2010-2019 Oleg Khabarov, 2024-2026 ShakaCode LLC, 2026 Andrew vonderLuft.
Released under the MIT License.