Installation
Add cm-admin to an existing Rails app and mount it at /admin.
Requirementsβ
| Requirement | Version |
|---|---|
| Ruby | 3.3 or later |
| Rails | 8.0 or later |
| Node.js | Needed at build time: assets:precompile compiles cm-admin's CSS with Dart Sass (CSS bundler) |
| PaperTrail | Needed for roles and record history (paper_trail gem) |
1. Add the gemβ
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, anAuthenticationconcern and theCurrentmodel. - OTP login? Use the built-in flow: see Authentication & OTP.
- Existing auth? Set
Current.userin abefore_actionof 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.
Missing a model in the sidebar? Every model must be listed in config.included_models in config/initializers/cm_admin.rb.