Sm Host Setup

sm-host-setup: Host Application Setup

Guides integration of the SourceMonitor engine into a host Rails application.

When to Use

• Adding SourceMonitor to a new or existing Rails 8 host app
• Troubleshooting a broken installation
• Re-running setup after upgrading the gem (see also: sm-upgrade skill for full upgrade workflow)
• Rolling back the engine from a host app

Prerequisites

Installation Methods

Method 1: Guided CLI (Recommended)

The engine ships a guided installer that handles every step interactively.

# From the host app root:
bundle add source_monitor --version "~> 0.3.0"
bundle install
bin/source_monitor install

The guided workflow:

1. Checks prerequisites via DependencyChecker
2. Prompts for mount path (default: /source_monitor)
3. Ensures gem "source_monitor" in Gemfile, runs bundle install
4. Runs npm install if package.json exists
5. Executes bin/rails generate source_monitor:install --mount-path=...
6. Copies and deduplicates migrations, runs bin/rails db:migrate
7. Patches the initializer with navigation hint and optional Devise hooks
8. Runs verification and prints a report

Non-interactive mode:

bin/source_monitor install --yes

Method 2: Manual Step-by-Step

# 1. Add the gem
gem "source_monitor", "~> 0.3.0"  # in Gemfile
bundle install

# 2. Run the install generator (mounts engine, creates initializer, configures recurring jobs)
bin/rails generate source_monitor:install --mount-path=/source_monitor

# 3. Copy engine migrations
bin/rails railties:install:migrations FROM=source_monitor

# 4. Apply migrations
bin/rails db:migrate

# 5. Start background workers (recurring jobs configured automatically in config/recurring.yml)
bin/rails solid_queue:start

# Note: The generator automatically patches Procfile.dev with a jobs: entry
# and adds recurring_schedule to your queue.yml dispatcher config.
# Re-run the generator if these were not applied: bin/rails generate source_monitor:install

# 6. Verify
bin/source_monitor verify

Method 3: GitHub Edge

# Gemfile
gem "source_monitor", github: "dchuk/source_monitor"

What the Install Generator Does

The generator (SourceMonitor::Generators::InstallGenerator) performs five actions:

1. Mounts the engine in config/routes.rb:

   mount SourceMonitor::Engine, at: "/source_monitor"
   

   Skips if already mounted. The mount path is configurable via --mount-path.

2. Creates the initializer at config/initializers/source_monitor.rb: Uses the template at lib/generators/source_monitor/install/templates/source_monitor.rb.tt. Skips if the file already exists.

3. Configures recurring jobs in config/recurring.yml: Adds entries for ScheduleFetchesJob (every minute), scrape scheduling (every 2 minutes), ItemCleanupJob (2am daily), and LogCleanupJob (3am daily). If the file doesn't exist, creates it with default: &default and environment sections. If it exists, merges entries without overwriting. Skips if SourceMonitor entries are already present.

4. Patches Procfile.dev with a jobs: entry for Solid Queue: Creates the file with web: and jobs: entries if it does not exist. Appends a jobs: entry if the file exists but lacks one. Skips if a jobs: entry is already present.

5. Patches queue.yml dispatcher with recurring_schedule: config/recurring.yml: Adds the recurring_schedule key to each dispatcher entry in config/queue.yml. If no dispatchers section exists, creates a default one. Skips if recurring_schedule is already configured. Skips if config/queue.yml does not exist.

Re-running the generator is safe and idempotent.

Post-Install Configuration

After installation, review and customize the initializer. Key areas:

See the sm-configure skill for full configuration reference.

Verification

# CLI verification
bin/source_monitor verify

# Rake task verification
bin/rails source_monitor:setup:verify

# Prerequisite check only
bin/rails source_monitor:setup:check

Verification checks Solid Queue workers and Action Cable health. Non-zero exit on failure.

Enable telemetry logging:

SOURCE_MONITOR_SETUP_TELEMETRY=true bin/source_monitor verify
# Logs to log/source_monitor_setup.log

Authentication (Fail-Closed by Default)

SourceMonitor is fail-closed by default: with no authenticate_with/authorize_with handler configured, every engine route (including create/update/delete/enqueue actions) returns 403 Forbidden. You must make one of two choices during setup:

1. Configure a handler (recommended) -- the handler decides access and bypasses the fail-closed guard.
2. Set config.authentication.open_access = true -- opts out of the guard so routes are public. Demo/non-production only. A configured handler always takes precedence over this flag.

When Devise is detected, the guided installer offers to wire authentication hooks:

config.authentication.authenticate_with :authenticate_user!
config.authentication.authorize_with ->(controller) {
  controller.current_user&.respond_to?(:admin?) ? controller.current_user.admin? : true
}
config.authentication.current_user_method = :current_user
config.authentication.user_signed_in_method = :user_signed_in?

Rollback

1. Remove gem "source_monitor" from Gemfile, bundle install
2. Delete config/initializers/source_monitor.rb
3. Remove mount SourceMonitor::Engine from config/routes.rb
4. Drop tables: bin/rails db:migrate:down VERSION=<timestamp> for each engine migration
5. Remove Solid Queue/Cable migrations only if no other components need them

Host Compatibility

Key Source Files

References

• docs/setup.md -- Complete setup workflow documentation
• docs/configuration.md -- Configuration reference
• docs/troubleshooting.md -- Common issues and fixes
• sm-upgrade skill -- Upgrade workflow for gem version updates

Testing

After setup, verify with:

1. bin/source_monitor verify -- Checks Solid Queue and Action Cable
2. Visit the mount path in browser -- Dashboard should load
3. Create a source and trigger "Fetch Now" -- Validates end-to-end
4. For subsequent gem updates, use bin/rails source_monitor:upgrade -- see the sm-upgrade skill

Optional system test for host apps using Devise:

# test/system/source_monitor_setup_test.rb
require "application_system_test_case"

class SourceMonitorSetupTest < ApplicationSystemTestCase
  test "signed in admin can reach SourceMonitor" do
    user = users(:admin)
    sign_in user
    visit "/source_monitor"
    assert_text "SourceMonitor Dashboard"
  end
end

Checklist

• Ruby 3.4+, Rails 8.0+, PostgreSQL 14+ available
• gem "source_monitor" added to Gemfile
• bundle install completed
• Install generator ran (bin/rails generate source_monitor:install)
• Engine migrations copied and applied
• Recurring jobs configured in config/recurring.yml
• Procfile.dev includes jobs: entry for Solid Queue (handled by generator)
• Dispatcher config includes recurring_schedule: config/recurring.yml (handled by generator)
• Solid Queue workers started
• Authentication decision made (engine is fail-closed by default): handler configured via authenticate_with/authorize_with, OR config.authentication.open_access = true for demos only
• bin/source_monitor verify passes
• Dashboard accessible at mount path