Kamal Hooks

Lean CMS provides Kamal deployment hooks for safer deployments. These hooks integrate with Kamal’s hook system to add pre-flight checks and post-deployment tasks.

Installation

Run the generator to install the hooks:

rails generate lean_cms:install_kamal_hooks

This creates:

  • .kamal/hooks/pre-deploy — runs before deployment
  • .kamal/hooks/post-deploy — runs after deployment

Pre-deploy hook

The pre-deploy hook performs safety checks before allowing a deployment.

Uncommitted changes check

Blocks deployment if you have uncommitted changes:

ERROR: You have uncommitted changes!

Uncommitted files:
  app/models/user.rb
  config/routes.rb

Please commit your changes before deploying:
  git add .
  git commit -m 'Your commit message'

This prevents accidentally deploying work-in-progress code.

Untracked files warning

Warns (but doesn’t block) if you have untracked files:

WARNING: You have untracked files that won't be deployed:
  app/services/new_feature.rb
  spec/new_spec.rb

Consider adding them to .gitignore or committing them.

Detached HEAD warning

Warns if you’re not on a branch:

WARNING: You're in detached HEAD state.
Consider checking out a branch before deploying.

Deployment info

Shows what commit will be deployed:

Deploying commit: a523156
  Message: Add content sync feature

Post-deploy hook

The post-deploy hook runs after a successful deployment.

Cache clearing

Automatically clears Rails cache on the production container:

kamal app exec "bin/rails runner 'Rails.cache.clear'"

Deployment logging

Logs the deployment details:

Deployment complete!
  Commit: a523156
  Time:   2024-12-03 10:30:00

Notifications (optional)

The hook includes a commented-out example for sending deploy notifications:

# Uncomment and configure as needed
curl -X POST "https://your-webhook-url" \
  -H "Content-Type: application/json" \
  -d "{\"text\": \"Deployed $COMMIT to production at $TIMESTAMP\"}"

Customization

The hooks live in your project’s .kamal/hooks/ directory. You can modify them to suit your needs:

  • Add additional checks (test suite, linting)
  • Integrate with your notification system (Slack, Discord, etc.)
  • Include a database backup step before deploy

Bypassing hooks

For emergency deploys when you need to skip the pre-deploy check:

# Option 1: Stash changes
git stash
kamal deploy
git stash pop

# Option 2: Temporarily disable the hook
mv .kamal/hooks/pre-deploy .kamal/hooks/pre-deploy.bak
kamal deploy
mv .kamal/hooks/pre-deploy.bak .kamal/hooks/pre-deploy