Scheduled Tasks

Convox can set up cron-like recurring tasks on any of your application processes. This can be useful for background work like data dumps, batch jobs, or even queueing other background jobs for a worker.

Configuring tasks

Scheduled tasks are configured in docker-compose.yml using labels in the convox.cron namespace. The label format is:

convox.cron.<task name>=<cron expression> <command>

Example: to run the command bin/myjob every hour on the web process, you would configure the label like this:

web:
  labels:
    - convox.cron.myjob=0 * * * ? bin/myjob

Cron expression format

Cron expressions use the following format. All times are UTC.

.----------------- minute (0 - 59)
|  .-------------- hour (0 - 23)
|  |  .----------- day-of-month (1 - 31)
|  |  |  .-------- month (1 - 12) OR JAN,FEB,MAR,APR ...
|  |  |  |  .----- day-of-week (1 - 7) OR SUN,MON,TUE,WED,THU,FRI,SAT
|  |  |  |  |
*  *  *  *  *

Using both day-of-week and day-of-month in the same expression is not supported. One of these fields must be a ?.

The actual start time of a job may be skewed up to 10 seconds. This is done to prevent infrastructure throttling errors when lots of jobs start at the same time. If you need to ensure that jobs are started in a specific order, make sure to start them at least 10 seconds apart.

Some example expressions:

Expression Meaning
* * * * ? Run every minute
*/10 * * * ? Run every 10 minutes
0 * * * ? Run every hour
30 6 * * ? Run at 6:30am UTC every day
30 18 ? * MON-FRI Run at 6:30pm UTC every weekday
0 12 1 * ? Run at noon on the first day of every month
0 0,12 * * ? Run at Midnight and Noon every day

See the Scheduled Events AWS documentation for more details.

Run options and persistence

The service a scheduled task is associated with does not necessarily need running containers all the time. The service can be scaled down to -1 or 0, and the scheduled task will “wake it up,” causing a container to be created for the scheduled to task to run in, and exiting when it finishes.