Excerpt
Whenever is a Ruby gem that provides a clear syntax for writing and deploying cron jobs.
### Installation
```plain text
$ gem install whenever
```
Or with Bundler in your Gemfile.
```plain text
gem 'whenever', require: false
```
### Getting started
```plain text
$ cd /apps/my-great-project
$ wheneverize .
```
This will create an initial config/schedule.rb file for you (as long as the config folder is already present in your project).
### The whenever command
```plain text
$ cd /apps/my-great-project
$ whenever
```
This will simply show you your schedule.rb file converted to cron syntax. It does not read or write your crontab file; you'll need to do this in order for your jobs to execute:
```plain text
$ whenever --update-crontab
```
Other commonly used options include:
```plain text
$ whenever --user app # set a user as which to install the crontab
$ whenever --load-file config/my_schedule.rb # set the schedule file
$ whenever --crontab-command 'sudo crontab' # overri
Whenever is a Ruby gem that provides a clear syntax for writing and deploying cron jobs.
### Installation
```plain text
$ gem install whenever
```
Or with Bundler in your Gemfile.
```plain text
gem 'whenever', require: false
```
### Getting started
```plain text
$ cd /apps/my-great-project
$ wheneverize .
```
This will create an initial config/schedule.rb file for you (as long as the config folder is already present in your project).
### The whenever command
```plain text
$ cd /apps/my-great-project
$ whenever
```
This will simply show you your schedule.rb file converted to cron syntax. It does not read or write your crontab file; you'll need to do this in order for your jobs to execute:
```plain text
$ whenever --update-crontab
```
Other commonly used options include:
```plain text
$ whenever --user app # set a user as which to install the crontab
$ whenever --load-file config/my_schedule.rb # set the schedule file
$ whenever --crontab-command 'sudo crontab' # override the crontab command
```
You can list installed cron jobs using crontab -l.
Run whenever --help for a complete list of options for selecting the schedule to use, setting variables in the schedule, etc.
### Example schedule.rb file
```plain text
every 3.hours do # 1.minute 1.day 1.week 1.month 1.year is also supported
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 1.day, at: ['4:30 am', '6:00 pm'] do
runner "Mymodel.task_to_run_in_two_times_every_day"
end
every :hour do # Many shortcuts available: :hour, :day, :month, :year, :reboot
runner "SomeModel.ladeeda"
end
every :sunday, at: '12pm' do # Use any day of the week or :weekend, :weekday
runner "Task.do_something_great"
end
every '0 0 27-31 * *' do
command "echo 'you can use raw cron syntax too'"
end
# run this task only on servers with the :app role in Capistrano
# see Capistrano roles section below
every :day, at: '12:20am', roles: [:app] do
rake "app_server:task"
end
```
### Parsing dates and times
Whenever uses the Chronic gem to parse the specified dates and times.
You can set your custom Chronic configuration if the defaults don't fit you.
For example, to assume a 24 hour clock instead of the default 12 hour clock:
```plain text
set :chronic_options, hours24: true
# By default this would run the job every day at 3am
every 1.day, at: '3:00' do
runner "MyModel.nightly_archive_job"
end
```
You can see a list of all available options here: https://github.com/mojombo/chronic/blob/master/lib/chronic/parser.rb
If we set whenever_roles to [:db, :app] in deploy.rb, and have the following jobs in schedule.rb:
```plain text
every :day, at: '1:37pm', roles: [:app] do
rake 'app:task' # will only be added to crontabs of :app servers
end
every :hour, roles: [:db] do
rake 'db:task' # will only be added to crontabs of :db servers
end
every :day, at: '12:02am' do
command "run_this_everywhere" # will be deployed to :db and :app servers
end
```
Here are the basic rules:
1. If a server's role isn't listed in whenever_roles, it will never have jobs added to its crontab.
2. If a server's role is listed in the whenever_roles, then it will have all jobs added to its crontab that either list that role in their :roles arg or that don't have a :roles arg.
3. If a job has a :roles arg but that role isn't in the whenever_roles list, that job will not be deployed to any server.