Skip to main content

Catalyst Setup

This guide covers how to set up the cm-admin gem (internally referred to as Catalyst) locally and connect it to another Rails application for development and testing.

Overview​

cm-admin is a Ruby on Rails admin panel gem. This repository contains both the gem source and a feature-app/ Rails application that can be used to test changes.

When developing new features or fixing bugs, you typically want to point a host Rails app at your local copy of cm-admin instead of the published gem.

Prerequisites​

  • Ruby 3.3.0 or higher
  • Bundler
  • A supported Rails application (the feature-app/ in this repo or another project)
  • PostgreSQL (if running the feature-app/)
  • Node.js (if building the documentation site)

Local Setup​

1. Clone the repository​

git clone git@github.com:commutatus/cm-admin.git
cd cm-admin

2. Install gem dependencies​

bundle install

This installs the dependencies declared in the root Gemfile.

3. Run the feature app​

The feature-app/ directory is a Rails application configured to load cm-admin from the local path.

cd feature-app
bundle install
bin/rails db:prepare
bin/rails server

Visit http://localhost:3000 to see the admin panel in action.

Connect to Another Local App​

To test cm-admin changes in a different Rails project, point that project's Gemfile to your local checkout.

1. Update the host app's Gemfile​

Open the host app's Gemfile and change the cm-admin line to use a local path:

gem 'cm-admin', path: '../cm-admin'

Make sure the relative path matches your directory layout. For example, if cm-admin and the host app are siblings:

workspace/
├── cm-admin/
└── my-rails-app/

Then the path from my-rails-app is ../cm-admin.

2. Install dependencies​

cd my-rails-app
bundle install

Bundler will now resolve cm-admin from the local directory instead of RubyGems or GitHub.

3. Restart the server​

bin/rails server

Any code changes you make in cm-admin/ are reflected in the host app after a server restart.

Verify Changes​

When making changes to the gem:

  1. Edit the source files in the root cm-admin directory.
  2. Restart the host app or feature-app server.
  3. Reload the page in your browser.

If the change affects assets, styles, or JavaScript, you may also need to clear the host app's tmp cache:

bin/rails tmp:clear

Troubleshooting​

  • Bundle cannot find the local gem: Double-check the relative path: in the host app's Gemfile.
  • Changes not appearing: Restart the Rails server. The gem is loaded at boot time, not on every request.
  • Database errors in feature-app: Run bin/rails db:prepare or bin/rails db:create db:migrate before starting the server.
  • Sprockets or asset errors: Make sure the host app includes the required cm-admin assets in its manifests.