Schedule Rails tasks with Whenever

The whenever gem turns a Ruby schedule into system crontab entries. Keep config/schedule.rb in source control and update the crontab during deployment. The cron daemon, rather than the gem itself, triggers the generated commands.

1. Install Whenever

# Gemfile
gem 'whenever', require: false

bundle install
bundle exec wheneverize .

The second command creates config/schedule.rb.

2. Define the schedule

# Clean up expired sessions daily at 02:00.
every 1.day, at: '2:00 am' do
  rake 'sessions:cleanup'
end

# Synchronize data every ten minutes.
every 10.minutes do
  runner 'SyncService.call'
end

# Enqueue an Active Job report every Monday.
every :monday, at: '6:30 am' do
  runner 'WeeklyReportJob.perform_later'
end

Supply the Rake task, service, and job in your application. Whenever's built-in task types are:

• rake: run a Rake task, commonly defined under lib/tasks/.
• runner: execute Ruby code inside the Rails environment.
• command: execute a shell command.

There is no built-in job task type for Active Job. Use runner as above, and run the workers required by your configured queue adapter.

3. Install the generated entries

bundle exec whenever --update-crontab
crontab -l

Whenever marks the section it manages so subsequent updates replace that section without replacing unrelated entries. Use a stable, distinct crontab identifier when several applications share a task account.

4. Integrate deployment

For Capistrano 3, require the integration in Capfile:

require 'whenever/capistrano'

Set deployment options in config/deploy.rb, for example:

set :whenever_command, 'bundle exec whenever'

Follow the integration instructions for your Capistrano version and restrict scheduling to the intended server role. In Docker or Kubernetes, updating a crontab is not enough: the container also needs a running cron daemon and the required application environment. Avoid installing the same schedule on every application replica unless duplicate triggers are intentional. A dedicated scheduling role is a common arrangement.

After an update, verify an actual task's start, completion, and exit result. Collect Rails logs and task output with DataKit and search by task name and run time. A cron trigger record alone does not prove successful execution.

FAQ

Why did editing schedule.rb have no effect?

It is the source definition. Run bundle exec whenever --update-crontab again to install the generated entries.

Why is the task running in the wrong time zone?

Cron's scheduling time zone and the application's display time zone may differ. Check the host/container and cron implementation. set :chronic_options, hours24: true changes time-string parsing, not the scheduling time zone. A container's TZ variable is not a universal guarantee that cron will use it; verify the daemon's supported configuration.

How do I remove Whenever's entries?

Run bundle exec whenever --clear-crontab, using the same identifier supplied when installing the schedule. This clears the corresponding managed section.

See the Whenever documentation for built-in job types and deployment integration.