Cron Jobs

Last Updated October 2014

Cron Jobs allow you to create schuduled tasks for your Pagoda Box application. They are commonly used to automate system maintenance or administration, but can also be used for many other things. This doc covers the basics of using cron jobs on Pagoda Box. After reading it, you should be familiar with:

  • Scheduling Cron jobs
  • Adding Cron Jobs to your app
  • Smiling as automated tasks run without your

Video Overview

How Cron Jobs Work

Whenever you add a cron job to your application, the job is loaded into the Crontab (Cron Table) of an instance within the service to which the cron job is assigned. For multi-instance services, only one instance will have the job added to its crontab. This prevents the job from running on all instances at the same time. Note that cron jobs are subject to the configuration of the instance on which they run, including things like memory limits and timeouts.

Creating a Cron Job

Cron Jobs can be created in both your App Dashboard and from your Boxfile.

Through the Dashboard

To add a cron job in the Dashboard, go to Cron Jobs under your Dev Config tab and click "New Cron Job."

The settings for the cron job are covered in detail below.

In the Boxfile

To configure a cron job using the Boxfile, nest a cron job under the appropriate service. You need to include both the cron schedule and the cron command.The cron will run using the resources available to the service to which it's assigned.

Cron Jobs in the Boxfile YAML

  web1:
    cron:
    # - "schedule": "command"
      - "0 0 * * *": "rm -rf app/cache/*"
      - "*/3 */2 1-3 2,6,7 2": "sh cron/script.sh'"
/Boxfile

On your next deploy, your cron job(s) will be created.

Removing/Editing Cron Jobs in Your Boxfile

It's important to note that when you remove a Cron Job from your Boxfile, it will not remove the Cron Job from your application. This can only be done in your App Dashboard.

Also, if you make an edit to a Cron Job in your Boxfile, it will not edit the existing job, but create a new Cron Job instead. You will need to delete the previous version of your job in your App Dashboard.

Cron Job Configuration

Cron jobs are really simple to configure, but there are some things you should know. With each cron, there are 4 main configuration settings:

Command

The command is script or process that runs when the cron job fires. It's important to note that only certain executables are available when using Cron Jobs. When defining the command, you have 2 options for declaring your executable.

  1. Including the executable in your command: "bash cron/script.sh".

  2. Declaring the executable in your script with a shebang (#!).

    If your script includes a shebang, you don't need to include the executable in the command, but you do need to be sure the file has executable permissions. Below is an example of what the command and script would look like:

Boxfile Cron Job without a Declared Executable YAML

  web1:
    cron:
      - "0 * * * *": "cron/script.php"
/Boxfile

PHP Script with a Shebang PHP

  #!/usr/bin/env php

  
/Boxfile

Shebang paths are explained in the Available Executables documentation. The filepath used in your commands can be either the relative path (relative to the root of your repo) or the absolute path:

  • Relative: path/to/script.php

  • Absolute: /var/www/path/to/script.php

Schedule

The schedule defines when and how often your cron job should run. Use Cron Expressions to define the schedule. Below are some simple examples:

Interval Description Schedule
Yearly Run once a year, midnight, Jan. 1st 0 0 1 1 *
Monthly Run once a month, midnight, first of month 0 0 1 * *
Weekly Run once a week, midnight on Sunday 0 0 * * 0
Daily Run once a day, midnight 0 0 * * *
Hourly Run once an hour, beginning of hour 0 * * * *

Be aware that Predefined Scheduling Definitions(e.g. @daily, @hourly, etc.) are not available on Pagoda Box. All schedules must be numeric.

Cron Jobs Run Based on Your App's Timezone

When defining your cron schedule, know that it will run based on your app's timezone.

Service

The Service defines on which of your app's services the cron job will run. If you define your cron job in your Boxfile, the service is set to the service under which the cron is nested. If you define your cron job in your dashboard and you have more than one service, you'll have the option to select which one you'd like to use.

It's important to note that cron jobs run in the environment of their selected service, so they are subject to the specified configuration of the service. For example, if a cron job writes to a network directory, the selected service must have access to that network directory.

Output Emails

This is pretty self-explanatory. Pagoda Box allows you to specify email addresses to notify when your Cron Job runs. The email includes the actual output of the script or command. You can specify these email addresses in your App Dashboard when creating a new Cron Job or editing an existing job. Adding notification email addresses can not be done in the Boxfile.

Output Emails Go Through Your SMTP Provider

Cron output emails are sent through the SMTP provider you provide in your dashboard. In order to have the output of your cron jobs emailed to you, you must first configure SMTP credentials in your dashboard.

If you have any questions, suggestions, or corrections, let us know.