Craken
======

Craken is a rails plugin for managing and installing rake-centric crontab files 
over Capistrano.

What is a crontab?  A command list that cron will run at specified intervals.
What is cron?  A daemon to execute scheduled commands.

If you don't know these things already you should probably do a little research
before using this tool :)

Craken uses files called raketabs that are similar in every respect to crontab
files except the commands are rake tasks instead of arbitrary unix commands.  The file
goes in the craken directory inside config (i.e. #{RAILS_ROOT}/config/craken/raketab).

Why not just let it run arbitrary commands instead of limiting it to rake tasks?
The main issue this plugin attempts to alleviate is having to manage the 
rails environment configuration for multiple deployments.  Craken will set up the
crontab to change into the application's current directory and set rake to run in
the correct environment.

Raketab files can also handle ERB escaped text bound to the rake environment.

A Capistrano file is also included to make it easy to install cron jobs on multiple 
hosts.  A new :cron capistrano role is necessary to define which machines to install to.

Configuration
=============

Command line configuration options to the rake task (defaults are in parens):
deploy_path        Where the application is deployed (RAILS_ROOT)
crontab_exe        Where to find the crontab excutable (/usr/bin/crontab)
rake_exe           The rake executable (/usr/bin/rake)
raketab_rails_env  Rails environment mode to set the cron jobs to run in (RAILS_ENV)
app_name           Name of the application (tries to figure it out from the deploy path)
raketab_file       Where the raketab file is 
                   (#{RAILS_ROOT}/config/craken/#{HOSTNAME}_raketab or 
                    #{RAILS_ROOT}/config/craken/raketab if the first is not found)


Example
=======

An example line from an example raketab file:

59 * * * * thing:to_do > /tmp/thing_to_do.log 2>&1

This will run the rake task thing:to_do every 59th minute after every hour.
The little redirect thing is added for effect; otherwise output will be mailed
to the user who the crontab is installed on.

When craken:install is run on the production box, the crontab will look like this:

### foo raketab
59 * * * * cd /home/thatguy/u/apps/foo/current && /usr/bin/rake --silent RAILS_ENV=production thing:to_do > /tmp/thing_to_do.log 2>&1
### foo raketab end

The "magic" part of craken is the bit that crontab added:
  cd /home/thatguy/u/apps/foo/current && /usr/bin/rake --silent RAILS_ENV=production


Running the Capistrano Script
-----------------------------

cap craken:install

Deploying to someplace other than production?  Rails environment is important so rake 
is set in the right mode when the cron job runs:

cap -c rails_env=qa craken:install

Different raketab files can be used to limit a subset of rake tasks to a particular 
machine listed as a :cron role.  These files are prefixed with the name of the machine
they need to be deployed to:

foo_raketab  # goes on the "foo" machine
bar_raketab  # goes on the "bar" machine
raketab      # goes on all machines except "foo" and "bar"


Doug McInnes <doug.mcinnes@latimes.com>
John Dewey <john.dewey@latimes.com>
Copyright (c) 2008 Los Angeles Times, released under the MIT license