Skip to main content

Configure Cronjobs

The cronjobs block in your config.cap.yaml defines tasks that run on a schedule. Each cronjob needs a unique name of at most 32 characters, a schedule, and either a command or a subcommand to run.

cronjobs:
  daily-cleanup:
    schedule: 0 2 * * *
    command: php /app/cleanup.php
    timeZone: Europe/Amsterdam

Options

Property Type Description Default
schedule string A cron expression or an alias such as @daily. See YAML Schema Reference. Required
timeZone string The time zone the schedule is interpreted in. Must be a valid time zone identifier. Etc/UTC
allowConcurrent boolean Whether a new run may start while the previous one is still going. When false, the new run is skipped. false
tries integer How many times the job runs before it is given up on, counting the first attempt. See Retrying a failed run. 1
command string or array The full command line to run, including a binary such as php. See Command or subcommand. None
subcommand string or array The command to run with your framework's binary. See Command or subcommand. The name
resources.cpu integer or string CPU allocated to each run. A number of cores, or thousandths such as 100m. 125m
resources.memory integer or string Memory allocated to each run. A number of bytes, or a value with a unit such as 256Mi. 256Mi
variables object Environment variables for this cronjob only, on top of the global ones. See Environment Variables. None

command and subcommand cannot both be set on the same cronjob.

Command or subcommand

Every cronjob runs one of two things. command is the full command line, exactly as you would type it. subcommand is just the part after your framework's binary, and CAP fills in the rest from your application type.

cronjobs:
  cleanup:
    schedule: "@daily"
    subcommand: app:cleanup              # php artisan app:cleanup
  legacy:
    schedule: 0 2 * * *
    command: php /app/bin/cleanup.php    # run verbatim

Which binary a subcommand gets depends on the type: php artisan on Laravel, php bin/console on Symfony and Shopware, php bin/cake on CakePHP, npm run on Node. See Application Types for the full list.

Omitting both runs the cronjob's own name as the subcommand, so a cronjob named cleanup runs php artisan cleanup on Laravel.

Unlike a worker, a cronjob runs once per schedule and is expected to exit, so its subcommand is not wrapped in a supervisor.

Custom base image required for subcommands. The subcommand option relies on a binary that only exists in our base container. Use command if you build your own image.

Retrying a failed run

A cronjob runs once per schedule and is not tried again if it fails. Raise tries where a failure is worth another attempt, for example when the job depends on something that is occasionally briefly unavailable.

cronjobs:
  sync-orders:
    schedule: "@hourly"
    subcommand: orders:sync
    tries: 3

tries counts the first attempt, so tries: 3 means the job runs up to three times before it is given up on. Values below 1 are rejected. A retry starts the command over from the beginning, so only raise it for a job that is safe to run twice.

Back to top