Whenever Ruby Gem

To automate crontab updates during deployment with Capistrano V3:

1. Add require "whenever/capistrano" to your Capfile.
2. Configure variables in config/deploy.rb. Use defer to ensure variables like :stage are evaluated at runtime.

Common configuration keys:

• whenever_identifier: Used to namespace crontab entries (e.g., #{fetch(:application)}_#{fetch(:stage)}).
• whenever_environment: Sets the environment (e.g., stage or production).
• whenever_load_file: Path to a custom schedule file.

By default, jobs are deployed to all servers in the whenever_roles list (which defaults to [:db]). To restrict a job to specific servers, use the roles: [...] argument in schedule.rb.

Important: The roles you specify in schedule.rb must also be included in the whenever_roles list in your deploy.rb for them to be considered.

Rules:

1. If a server's role is not in whenever_roles, it gets no jobs.
2. If a server's role is in whenever_roles, it gets all jobs that either list that role or have no :roles argument.
3. If a job specifies a role that is not in whenever_roles, that job is not deployed anywhere.

You can install the Whenever gem directly via the command line or by adding it to your Gemfile using Bundler.

$ gem install whenever

Or in your Gemfile:

gem 'whenever', require: false

To set up a new Whenever configuration in your project, navigate to your project root and run wheneverize. This creates a config/schedule.rb file (provided the config directory already exists).

$ cd /apps/my-great-project
$ bundle exec wheneverize .

Whenever uses the Chronic gem for parsing dates. You can pass custom options to Chronic using set :chronic_options.

set :chronic_options, hours24: true

every 1.day, at: '3:00' do
  runner "MyModel.nightly_archive_job"
end

The Whenever Capistrano integration provides logic to manage crontab updates during deployments and rollbacks:

1. Standard Rollback: If a :previous_release is available, the integration updates the crontab to point to the previous release's path.
2. No Previous Release: If no previous release is found, the integration clears the crontab using the flags defined in :whenever_clear_flags and the current :release_path.

The wheneverize command is a CLI tool used to initialize a new Whenever configuration file (config/schedule.rb) in your project. It creates the directory structure and a template file containing example syntax for defining cron jobs.

If you run the command without arguments, it will attempt to create the configuration in the current directory. You can also specify a target directory.

The config/schedule.rb file uses a Ruby DSL to define cron jobs. You can use time shortcuts like 3.hours, :hour, :day, :weekend, or :sunday. You can also use raw cron syntax.

Supported job types include runner, rake, and command.

every 3.hours do
  runner "MyModel.some_process"
  rake "my:rake:task"
  command "/usr/bin/my_great_command"
end

every 1.day, at: '4:30 am' do
  runner "MyModel.task_to_run_at_four_thirty_in_the_morning"
end

every :sunday, at: '12pm' do
  runner "Task.do_something_great"
end

every '0 0 27-31 * *' do
  command "echo 'you can use raw cron syntax too'"
end

Whenever provides command, rake, script, and runner by default. You can define your own using job_type. The :task token is replaced by the first argument, and other tokens (like :fun_level) are replaced by options passed to the job.

job_type :awesome, '/usr/local/bin/awesome :task :fun_level'

every 2.hours do
  awesome "party", fun_level: "extreme"
end
# Runs: /usr/local/bin/awesome party extreme

You can add a description to a job which will appear as a comment in the crontab above the entry using the description: option.

every 1.hours, description: "My job description\nhas multiple lines" do
  command "/usr/bin/my_great_command"
end

You can redirect the output of your cron jobs using the :output option. This can be set globally for all jobs or specifically for an individual job.

• Global setting: set :output, 'path/to/log'
• Per-job setting: every 1.day, :output => 'path/to/log' do ... end

For backwards compatibility, :cron_log can also be used, but :output is the modern standard.