Skip to content

HTTPS clone URL

Subversion checkout URL

You can clone with
or
.
Download ZIP
Newer
Older
100644 245 lines (166 sloc) 8.486 kb
e66226e @javan created a new :job_template to wrap all commands with. using 'bash -l…
authored
1 Whenever is a Ruby gem that provides a clear syntax for writing and deploying cron jobs.
bfc46cc @javan updated readme
authored
2
46da1bc @javan converted rdoc files to markdown
authored
3 ### Installation
660fbc5 @javan update readme for syntax highlighting
authored
4
b4f7119 @richo whitespace
richo authored
5 ```sh
660fbc5 @javan update readme for syntax highlighting
authored
6 $ gem install whenever
7 ```
d567196 @javan updated readme
authored
8
e66226e @javan created a new :job_template to wrap all commands with. using 'bash -l…
authored
9 Or with Bundler in your Gemfile.
10
660fbc5 @javan update readme for syntax highlighting
authored
11 ```ruby
12 gem 'whenever', :require => false
13 ```
b4f7119 @richo whitespace
richo authored
14
46da1bc @javan converted rdoc files to markdown
authored
15 ### Getting started
d2eec9f @javan Initial commit.
authored
16
660fbc5 @javan update readme for syntax highlighting
authored
17 ```sh
16f988f @javan avoid confusion with 'app' directory
authored
18 $ cd /apps/my-great-project
660fbc5 @javan update readme for syntax highlighting
authored
19 $ wheneverize .
20 ```
d2eec9f @javan Initial commit.
authored
21
8a1be08 @vitorbal Fixed small mistake on readme.md
vitorbal authored
22 This will create an initial `config/schedule.rb` file for you.
d2eec9f @javan Initial commit.
authored
23
46da1bc @javan converted rdoc files to markdown
authored
24 ### Example schedule.rb file
d2eec9f @javan Initial commit.
authored
25
b4f7119 @richo whitespace
richo authored
26 ```ruby
660fbc5 @javan update readme for syntax highlighting
authored
27 every 3.hours do
b4f7119 @richo whitespace
richo authored
28 runner "MyModel.some_process"
29 rake "my:rake:task"
660fbc5 @javan update readme for syntax highlighting
authored
30 command "/usr/bin/my_great_command"
31 end
d2eec9f @javan Initial commit.
authored
32
b4f7119 @richo whitespace
richo authored
33 every 1.day, :at => '4:30 am' do
660fbc5 @javan update readme for syntax highlighting
authored
34 runner "MyModel.task_to_run_at_four_thirty_in_the_morning"
35 end
d2eec9f @javan Initial commit.
authored
36
660fbc5 @javan update readme for syntax highlighting
authored
37 every :hour do # Many shortcuts available: :hour, :day, :month, :year, :reboot
38 runner "SomeModel.ladeeda"
39 end
85fb895 @javan updated readme
authored
40
b4f7119 @richo whitespace
richo authored
41 every :sunday, :at => '12pm' do # Use any day of the week or :weekend, :weekday
660fbc5 @javan update readme for syntax highlighting
authored
42 runner "Task.do_something_great"
43 end
a94dda4 @javan allow raw cron sytanx
authored
44
660fbc5 @javan update readme for syntax highlighting
authored
45 every '0 0 27-31 * *' do
46 command "echo 'you can use raw cron syntax too'"
47 end
28d4118 @cap10morgan add info & examples for :roles feature to README
cap10morgan authored
48
0c71aee @cap10morgan fix small typo in README
cap10morgan authored
49 # run this task only on servers with the :app role in Capistrano
28d4118 @cap10morgan add info & examples for :roles feature to README
cap10morgan authored
50 # see Capistrano roles section below
51 every :day, :at => '12:20am', :roles => [:app] do
52 rake "app_server:task"
53 end
660fbc5 @javan update readme for syntax highlighting
authored
54 ```
be38dd1 Added output redirection support
Peer Allan authored
55
46da1bc @javan converted rdoc files to markdown
authored
56 ### Define your own job types
ad7a82b @javan wording change and added info about job_type to README
authored
57
e66226e @javan created a new :job_template to wrap all commands with. using 'bash -l…
authored
58 Whenever ships with three pre-defined job types: command, runner, and rake. You can define your own with `job_type`.
ad7a82b @javan wording change and added info about job_type to README
authored
59
60 For example:
61
660fbc5 @javan update readme for syntax highlighting
authored
62 ```ruby
63 job_type :awesome, '/usr/local/bin/awesome :task :fun_level'
64
65 every 2.hours do
66 awesome "party", :fun_level => "extreme"
67 end
68 ```
b4f7119 @richo whitespace
richo authored
69
e66226e @javan created a new :job_template to wrap all commands with. using 'bash -l…
authored
70 Would run `/usr/local/bin/awesome party extreme` every two hours. `:task` is always replaced with the first argument, and any additional `:whatevers` are replaced with the options passed in or by variables that have been defined with `set`.
ad7a82b @javan wording change and added info about job_type to README
authored
71
72 The default job types that ship with Whenever are defined like so:
73
660fbc5 @javan update readme for syntax highlighting
authored
74 ```ruby
75 job_type :command, ":task :output"
a8ba321 @andfx Renamed :env_argument to :environment_variable
andfx authored
76 job_type :rake, "cd :path && :environment_variable=:environment bundle exec rake :task --silent :output"
71eba37 @alvir Change 'script/rails' on 'bin/rails' in README.md
alvir authored
77 job_type :runner, "cd :path && bin/rails runner -e :environment ':task' :output"
a8ba321 @andfx Renamed :env_argument to :environment_variable
andfx authored
78 job_type :script, "cd :path && :environment_variable=:environment bundle exec script/:task :output"
660fbc5 @javan update readme for syntax highlighting
authored
79 ```
e66226e @javan created a new :job_template to wrap all commands with. using 'bash -l…
authored
80
24d4160 @javan futurize the readme
authored
81 Pre-Rails 3 apps and apps that don't use Bundler will redefine the `rake` and `runner` jobs respectively to function correctly.
82
a8ba321 @andfx Renamed :env_argument to :environment_variable
andfx authored
83 If a `:path` is not set it will default to the directory in which `whenever` was executed. `:environment_variable` will default to 'RAILS_ENV'. `:environment` will default to 'production'. `:output` will be replaced with your output redirection settings which you can read more about here: <http://github.com/javan/whenever/wiki/Output-redirection-aka-logging-your-cron-jobs>
e66226e @javan created a new :job_template to wrap all commands with. using 'bash -l…
authored
84
46da1bc @javan converted rdoc files to markdown
authored
85 All jobs are by default run with `bash -l -c 'command...'`. Among other things, this allows your cron jobs to play nice with RVM by loading the entire environment instead of cron's somewhat limited environment. Read more: <http://blog.scoutapp.com/articles/2010/09/07/rvm-and-cron-in-production>
e66226e @javan created a new :job_template to wrap all commands with. using 'bash -l…
authored
86
46da1bc @javan converted rdoc files to markdown
authored
87 You can change this by setting your own `:job_template`.
e66226e @javan created a new :job_template to wrap all commands with. using 'bash -l…
authored
88
660fbc5 @javan update readme for syntax highlighting
authored
89 ```ruby
90 set :job_template, "bash -l -c ':job'"
91 ```
b4f7119 @richo whitespace
richo authored
92
e66226e @javan created a new :job_template to wrap all commands with. using 'bash -l…
authored
93 Or set the job_template to nil to have your jobs execute normally.
ad7a82b @javan wording change and added info about job_type to README
authored
94
660fbc5 @javan update readme for syntax highlighting
authored
95 ```ruby
96 set :job_template, nil
97 ```
ad7a82b @javan wording change and added info about job_type to README
authored
98
46da1bc @javan converted rdoc files to markdown
authored
99 ### Capistrano integration
d2eec9f @javan Initial commit.
authored
100
90b26c1 @phallstrom Capistrano V3 Support
phallstrom authored
101 Use the built-in Capistrano recipe for easy crontab updates with deploys. For Capistrano V3, see the next section.
d2eec9f @javan Initial commit.
authored
102
436255e @javan added a built-in capistrano recipe
authored
103 In your "config/deploy.rb" file:
b82ef34 @javan updated readme
authored
104
660fbc5 @javan update readme for syntax highlighting
authored
105 ```ruby
106 require "whenever/capistrano"
107 ```
841c5a4 @javan updated readme, changelog, gemspec. bumped to 0.1.6
authored
108
f110f6f @drewrothstein fix capistrano recipe link
drewrothstein authored
109 Take a look at the recipe for options you can set. <https://github.com/javan/whenever/blob/master/lib/whenever/capistrano/v2/recipes.rb>
436255e @javan added a built-in capistrano recipe
authored
110 For example, if you're using bundler do this:
841c5a4 @javan updated readme, changelog, gemspec. bumped to 0.1.6
authored
111
660fbc5 @javan update readme for syntax highlighting
authored
112 ```ruby
113 set :whenever_command, "bundle exec whenever"
114 require "whenever/capistrano"
115 ```
841c5a4 @javan updated readme, changelog, gemspec. bumped to 0.1.6
authored
116
6f94747 @amiryal Fix documentation for Capistrano with different environments
amiryal authored
117 If you are using different environments (such as staging, production), then you may want to do this:
118
660fbc5 @javan update readme for syntax highlighting
authored
119 ```ruby
120 set :whenever_environment, defer { stage }
121 require "whenever/capistrano"
122 ```
6f94747 @amiryal Fix documentation for Capistrano with different environments
amiryal authored
123
660fbc5 @javan update readme for syntax highlighting
authored
124 The capistrano variable `:stage` should be the one holding your environment name. This will make the correct `:environment` available in your `schedule.rb`.
6f94747 @amiryal Fix documentation for Capistrano with different environments
amiryal authored
125
a96b3b7 @dleavitt Added a note to the README addressing multiple Cap environments on a …
dleavitt authored
126 If both your environments are on the same server you'll want to namespace them or they'll overwrite each other when you deploy:
127
128 ```ruby
129 set :whenever_environment, defer { stage }
130 set :whenever_identifier, defer { "#{application}_#{stage}" }
131 require "whenever/capistrano"
132 ```
133
90b26c1 @phallstrom Capistrano V3 Support
phallstrom authored
134 ### Capistrano V3 Integration
135
136 In your "Capfile" file:
137
138 ```ruby
58380c5 @phallstrom remove need to specify loading of capistrano3. Just load capistrano …
phallstrom authored
139 require "whenever/capistrano"
90b26c1 @phallstrom Capistrano V3 Support
phallstrom authored
140 ```
141
6751cfd @steven-ferguson Update README.md
steven-ferguson authored
142 Take a look at the load:defaults (bottom of file) task for options you can set. <https://github.com/javan/whenever/blob/master/lib/whenever/capistrano/v3/tasks/whenever.rake>. For example, to namespace the crontab entries by application and stage do this.
90b26c1 @phallstrom Capistrano V3 Support
phallstrom authored
143
e11b981 @s-osa Update README.md
s-osa authored
144 In your in "config/deploy.rb" file:
145
90b26c1 @phallstrom Capistrano V3 Support
phallstrom authored
146 ```ruby
147 set :whenever_identifier, ->{ "#{fetch(:application)}_#{fetch(:stage)}" }
148 ```
149
287cf84 @javan move capistrano roles docs down in the readme
authored
150 ### Capistrano roles
151
152 The first thing to know about the new roles support is that it is entirely
153 optional and backwards-compatible. If you don't need different jobs running on
154 different servers in your capistrano deployment, then you can safely stop reading
155 now and everything should just work the same way it always has.
156
157 When you define a job in your schedule.rb file, by default it will be deployed to
158 all servers in the whenever_roles list (which defaults to [:db]).
159
160 However, if you want to restrict certain jobs to only run on subset of servers,
161 you can add a :roles => [...] argument to their definitions. **Make sure to add
162 that role to the whenever_roles list in your deploy.rb.**
163
164 When you run `cap deploy`, jobs with a :roles list specified will only be added to
165 the crontabs on servers with one or more of the roles in that list.
166
167 Jobs with no :roles argument will be deployed to all servers in the whenever_roles
168 list. This is to maintain backward compatibility with previous releases of whenever.
169
170 So, for example, with the default whenever_roles of [:db], a job like this would be
171 deployed to all servers with the :db role:
172
173 ```ruby
174 every :day, :at => '12:20am' do
175 rake 'foo:bar'
176 end
177 ```
178
179 If we set whenever_roles to [:db, :app] in deploy.rb, and have the following
180 jobs in schedule.rb:
181
182 ```ruby
183 every :day, :at => '1:37pm', :roles => [:app] do
184 rake 'app:task' # will only be added to crontabs of :app servers
185 end
186
187 every :hour, :roles => [:db] do
188 rake 'db:task' # will only be added to crontabs of :db servers
189 end
190
191 every :day, :at => '12:02am' do
192 command "run_this_everywhere" # will be deployed to :db and :app servers
193 end
194 ```
195
196 Here are the basic rules:
197
198 1. If a server's role isn't listed in whenever_roles, it will *never* have jobs
199 added to its crontab.
200 1. If a server's role is listed in the whenever_roles, then it will have all
201 jobs added to its crontab that either list that role in their :roles arg or
202 that don't have a :roles arg.
203 1. If a job has a :roles arg but that role isn't in the whenever_roles list,
204 that job *will not* be deployed to any server.
205
7be0626 @JDutil I am adding RVM gotcha directions to the README since I ran into the …
JDutil authored
206 ### RVM Integration
207
208 If your production environment uses RVM (Ruby Version Manager) you will run into a gotcha that causes your cron jobs to hang. This is not directly related to Whenever, and can be tricky to debug. Your .rvmrc files must be trusted or else the cron jobs will hang waiting for the file to be trusted. A solution is to disable the prompt by adding this line to your user rvm file in `~/.rvmrc`
209
660fbc5 @javan update readme for syntax highlighting
authored
210 `rvm_trust_rvmrcs_flag=1`
7be0626 @JDutil I am adding RVM gotcha directions to the README since I ran into the …
JDutil authored
211
5f309f8 @phallstrom remove dead link to old RVM site. fixes #423
phallstrom authored
212 This tells rvm to trust all rvmrc files.
7be0626 @JDutil I am adding RVM gotcha directions to the README since I ran into the …
JDutil authored
213
46da1bc @javan converted rdoc files to markdown
authored
214 ### The `whenever` command
645a4af @javan Releasing v0.6.0 with better Rails 3 and RVM support.
authored
215
660fbc5 @javan update readme for syntax highlighting
authored
216 ```sh
ace7f08 @javan replaced another confusing 'app' dir
authored
217 $ cd /apps/my-great-project
660fbc5 @javan update readme for syntax highlighting
authored
218 $ whenever
219 ```
b4f7119 @richo whitespace
richo authored
220
660fbc5 @javan update readme for syntax highlighting
authored
221 This will simply show you your `schedule.rb` file converted to cron syntax. It does not read or write your crontab file. Run `whenever --help` for a complete list of options.
841c5a4 @javan updated readme, changelog, gemspec. bumped to 0.1.6
authored
222
46da1bc @javan converted rdoc files to markdown
authored
223 ### Credit
51f6839 @javan updated readme
authored
224
bbd5bcf @javan readme
authored
225 Whenever was created for use at Inkling (<http://inklingmarkets.com>). Their take on it: <http://blog.inklingmarkets.com/2009/02/whenever-easy-way-to-do-cron-jobs-from.html>
0b7bece @javan updated readme
authored
226
46da1bc @javan converted rdoc files to markdown
authored
227 Thanks to all the contributors who have made it even better: <http://github.com/javan/whenever/contributors>
51f6839 @javan updated readme
authored
228
46da1bc @javan converted rdoc files to markdown
authored
229 ### Discussion / Feedback / Issues / Bugs
bfc46cc @javan updated readme
authored
230
46da1bc @javan converted rdoc files to markdown
authored
231 For general discussion and questions, please use the google group: <http://groups.google.com/group/whenever-gem>
d2eec9f @javan Initial commit.
authored
232
46da1bc @javan converted rdoc files to markdown
authored
233 If you've found a genuine bug or issue, please use the Issues section on github: <http://github.com/javan/whenever/issues>
16fd6fb @javan Updated README with Lighthouse url and MIT license
authored
234
46da1bc @javan converted rdoc files to markdown
authored
235 Ryan Bates created a great Railscast about Whenever: <http://railscasts.com/episodes/164-cron-in-ruby>
e66226e @javan created a new :job_template to wrap all commands with. using 'bash -l…
authored
236 It's a little bit dated now, but remains a good introduction.
237
7ca2d87 @javan moved license
authored
238 ----
239
17f4cb8 @bkzl Update compatible Ruby versions in README
bkzl authored
240 Compatible with Ruby 1.8.7-2.2.0, JRuby, and Rubinius. [![Build Status](https://secure.travis-ci.org/javan/whenever.png)](http://travis-ci.org/javan/whenever)
8515ffb @javan added compatibility note to readme
authored
241
89c9148 @javan add rake to dev dependencies, add travis-ci status to readme
authored
242 ----
243
77af869 @alotofnoodles Update README.md
alotofnoodles authored
244 Copyright &copy; 2015 Javan Makhmali
Something went wrong with that request. Please try again.