Skip to main content

Installation

Add cm-admin to an existing Rails app and mount it at /admin.

Requirements​

RequirementVersion
Ruby3.3 or later
Rails8.0 or later
Node.jsNeeded at build time: assets:precompile compiles cm-admin's CSS with Dart Sass (CSS bundler)
PaperTrailNeeded for roles and record history (paper_trail gem)

1. Add the gem​

Gemfile
gem "cm-admin"
bundle install

2. Run the install generator​

rails generate cm_admin:install

This installs Action Text and i18n-active_record, mounts the engine at /admin, creates config/initializers/cm_admin.rb, app/policies/application_policy.rb and the cm_admin/custom.js / custom.css assets, and runs the file import/export migrations. See the Install generator for the full list.

3. Set up authentication​

cm-admin reads the signed-in user from Current.user.

  • No authentication yet? Run rails generate cm_admin:add_authentication. It sets up Devise, an Authentication concern and the Current model.
  • OTP login? Use the built-in flow: see Authentication & OTP.
  • Existing auth? Set Current.user in a before_action of your admin controllers.

4. Set up roles and permissions​

rails generate cm_admin:install_role
rails generate migration AddCmRoleToUser cm_role:references
rails db:migrate

This creates CmRole and CmPermission and an Admin role with every permission. Assign a role to your user (user.update!(cm_role: CmRole.find_by(name: "Admin"))). See Roles & Permissions.

5. Copy any remaining migrations​

rails cm_admin:install_migrations
rails db:migrate

Verify​

Start the server and open http://localhost:3000/admin. After signing in you should see the cm-admin dashboard.

tip

Missing a model in the sidebar? Every model must be listed in config.included_models in config/initializers/cm_admin.rb.

Next steps​