Catalyst Config

Catalyst Config is the mechanism cm-admin uses to bundle and sync deploy configuration files (like .hatchbox/) from the gem into your application. It works like Rails migrations — but for config files instead of database schema.

How It Works

deploy-config/            ← gem source (ships with cm-admin)
  .hatchbox/              ← synced to app_root/.hatchbox/
  (any future config)     ← synced to app_root/<name>

1. The gem stores all deploy config files in deploy-config/ at the gem root
2. rake cm_admin:deploy_config:sync copies everything inside deploy-config/ to your app root
3. A .deploy-config marker file at your app root records a SHA256 checksum of the bundled config
4. On every boot in development, cm-admin compares the stored checksum against the current checksum of the gem's deploy-config/ directory and warns if they differ

Checksum Tracking

The gem computes a SHA256 checksum of the deploy-config/ directory at runtime. The .deploy-config marker file at the app root contains the checksum that was last synced:

a3f5c2...

No manual version bump is needed — changing any file inside deploy-config/ produces a different checksum, which triggers the sync warning automatically.

Available Tasks

Task	Command	Description
Sync	rake cm_admin:deploy_config:sync	Copies everything from deploy-config/ to app root and writes the marker
Check	rake cm_admin:deploy_config:check	Fails (non-zero exit) if config is out of date — use in CI

Boot Check

In development, cm-admin checks config sync on every boot. If the marker checksum is stale or missing, you'll see:

⚠️  Deploy Config is out of date
  Run `rake cm_admin:deploy_config:sync` and commit the changes.

This never runs in production and never syncs automatically — you must run the sync task manually and commit the result.

Workflow for App Developers

When updating the cm-admin gem:

1. Run bundle update cm-admin
2. Start the app — if the boot warning appears, run rake cm_admin:deploy_config:sync
3. Commit the synced files (e.g. .hatchbox/, .deploy-config)
4. Deploy

For CI, add a check after bundle update:

bundle exec rake cm_admin:deploy_config:check

This fails the build if config is out of date, preventing deploying stale config.

Workflow for Gem Developers

Adding a New Config File or Folder

1. Create the file or folder inside deploy-config/:

deploy-config/
  .hatchbox/           ← existing
  .new-tool/           ← new — just drop it in
    ├── setup.sh
    └── config.yml

2. Commit and release a new gem version

That's it — no code changes needed. The checksum changes automatically, so all apps will get the sync warning on next boot and rake cm_admin:deploy_config:sync will copy the new files to their app root.

Modifying an Existing Config File

1. Edit the file inside deploy-config/ (e.g. deploy-config/.hatchbox/lib/config.rb)
2. Commit and release

Important Notes

• Sync is destructive: sync! removes existing files at the target before copying. Any app-local modifications to synced files will be overwritten.
• No manual version bump needed: The SHA256 checksum detects changes automatically when any file inside deploy-config/ is added, removed, or modified.
• Commit after syncing: The synced files must be committed to the app's git repo — deploy platforms like Hatchbox read from git, not from the gem at boot time.

Current Contents

Path	Purpose
deploy-config/.hatchbox/	Hatchbox deployment scripts with Slack notifications

See HatchboxScripts for details on the .hatchbox/ config.