Installation

Lean CMS installs into an existing Rails 8 application. There is no separate admin service to run — the CMS is mounted at /lean-cms inside your app.

1. Add to your Gemfile 

gem "lean_cms"

Lean CMS depends on paper_trail, view_component, kaminari, pundit, noticed, image_processing, meta-tags, rack-attack, and http. Bundler pulls them automatically — you do not need to list them yourself.

2. Run the installer 

bundle install
rails generate lean_cms:install
rails db:migrate

The installer:

  • Copies config/initializers/lean_cms.rb (site name, colors, admin path).
  • Creates config/lean_cms_structure.yml (your page structure definition, see Seeding Content).
  • Adds the gem’s migrations to your host app and runs them.

CMS routes are exposed under /lean-cms (the admin path is configurable in the initializer).

3. Configure the initializer

config/initializers/lean_cms.rb:

LeanCms.configure do |config|
  config.site_name       = "Acme Corp"
  config.site_logo_path  = "logo.png"          # served from app/assets/images
  config.primary_color   = "#2563eb"
  config.secondary_color = "#1e40af"
  config.admin_path      = "/lean-cms"
  config.user_class      = "User"              # your User model name
  config.posts_per_page  = 10
  config.portfolio_enabled = true
  config.mailer_from     = "noreply@example.com"
end

4. Wire up the User model

Lean CMS owns the session and magic-link tables, but the User model lives in your application. The minimum interface the gem expects:

class User < ApplicationRecord
  has_secure_password

  # NOTE: Lean CMS does NOT require has_many :sessions / :magic_links here.
  # It uses LeanCms::Session and LeanCms::MagicLink directly so it stays
  # compatible with Rails 8's built-in auth (which adds its own
  # has_many :sessions on the generated User).

  # Permission predicates — implement however you like.
  def can_edit_pages?;     is_super_admin? || can_edit_pages;     end
  def can_edit_blog?;      is_super_admin? || can_edit_blog;      end
  def can_manage_users?;   is_super_admin? || can_manage_users;   end
  def can_access_settings?;is_super_admin? || can_access_settings;end

  def has_any_cms_permission?
    can_edit_pages? || can_edit_blog? || can_manage_users? || can_access_settings?
  end

  # Called on successful login.
  def record_login!
    update_column(:last_login_at, Time.current)
  end

  def active?
    active
  end

  def must_change_password?
    must_change_password
  end
end

Required user columns: email_address (string, indexed unique), password_digest (string), active (boolean), must_change_password (boolean), last_login_at (datetime), plus your permission boolean columns (is_super_admin, can_edit_pages, can_edit_blog, can_manage_users, can_access_settings).

5. Add the authentication concern

In app/controllers/application_controller.rb:

class ApplicationController < ActionController::Base
  include LeanCms::Authentication
  # …
end

LeanCms::Authentication exposes current_user, authenticated?, start_new_session_for, and terminate_session to every controller in your app, and protects requests by default. Use the allow_unauthenticated_access class method to opt specific public actions out:

class PagesController < ApplicationController
  allow_unauthenticated_access
  # …
end

Lean CMS’s user-management controllers use Pundit policies (e.g. “can this admin modify that super-admin?”), but Pundit is included automatically by the gem’s own LeanCms::ApplicationController — your host AC doesn’t need to include it. Only add include Pundit::Authorization to your AC if you want authorize / policy_scope available in your own non-CMS controllers too. See the hybrid authorization model for when to use Pundit policies vs. the gem’s LeanCms::Authorization before_actions in your own controllers.

6. Include the content helper

In app/helpers/application_helper.rb:

module ApplicationHelper
  include LeanCms::PageContentHelper
end

This gives you page_content, editable_content, cms_editable_section, cards_section, bullets_section, and lean_cms_picture_tag in every view. See the Helper API.

7. Seed your first site

Define the structure in config/lean_cms_structure.yml (see Seeding Content) and load it:

rails lean_cms:load_structure

The task is idempotent — re-running it does not overwrite existing values.

8. Create the first admin user 

rails console

User.create!(
  email_address: "admin@example.com",
  password: "change-me",
  name: "Admin",
  active: true,
  is_super_admin: true
)

Then visit /lean-cms/login and log in.

Next steps