The top-level jobs element declares containers that run to completion, such
as database migrations and backups. A job runs when you start it with
docker compose run, on a cron schedule, or both. Docker Engine records every
execution of a job with its state and exit code.
jobs is a map whose keys are job names and whose values are job definitions.
Job names can contain letters, digits, ., _, and -.
A job definition supports all attributes defined in the Container specification and the Workload specification, as well as the following job-specific attributes.
A job can depend on services or on other jobs using depends_on, but a service cannot
depend on a job: the "run this job before my service starts" pattern is not what jobs
are for.
Jobs and services share one namespace. A name can't belong to both a service
and a job, so a name always refers to a single element, for example as the
target of a depends_on entry or of docker compose run. Compose returns an
error when a service and a job have the same name.
ImportantJobs are experimental and need the jobs extension turned on in Docker Engine.
Example
The following example declares a manual job and a scheduled job. Docker Engine
runs sync every 5 minutes, waits for a run in progress to finish before it
starts the next one, and skips the runs it missed while it was stopped:
jobs:
migrate:
image: example/migrations
triggers:
manual: true
sync:
image: example/sync
triggers:
schedule:
- cron: "*/5 * * * *"
concurrency: queue
missed_fires: skipAttributes
A job definition accepts the following attributes.
Container and workload attributes
A job accepts every attribute of the container specification
and the workload specification, the same attributes that
services share, and extends. It doesn't accept the other
service-specific attributes, which manage the lifecycle of a
long-running service:
| Attribute | Why it doesn't apply |
|---|---|
deploy, scale | A run is a single container; jobs have no replicas |
restart | A job runs to completion; see concurrency instead |
post_start, pre_start, pre_stop | Lifecycle hooks of a long-running service |
container_name | Each run creates its own container |
attach | docker compose run streams the output |
develop, provider, links, external_links | Not supported for jobs |
A job can set depends_on to services and to other
jobs. docker compose run starts the services and runs the jobs that a job
depends on first. A job that another job depends on runs as a regular
container and has no run record. Docker Engine doesn't evaluate depends_on
when it starts a scheduled job. A service can't set depends_on to a job.
profiles
profiles defines a list of named profiles for the job. A job with
profiles is only active when one of its profiles is active, unless you target
it with docker compose run. In that case, Compose activates its profiles. See
Profiles.
extends
extends lets a job share a common configuration with another job. It uses the
same syntax and merge rules as the extends attribute of services.
The value is a mapping with a required service key and an optional file key.
The attributes that the extending job declares override or complete the ones of
the base.
Services and jobs are extended separately. A job can only extend another job,
and a service can only extend another service. In the extends mapping,
service therefore holds the name of the job you reference, and file is a
Compose file that declares this job under its jobs top-level element. When
file isn't set, the referenced job is declared in the same Compose file.
jobs:
base-task:
image: myapp:latest
environment:
LOG_LEVEL: info
triggers:
manual: true
nightly-report:
extends:
service: base-task
command: ./generate-report.sh
triggers:
schedule:
- "0 3 * * *"The restrictions, the lookup of the referenced element, and the handling of circular references that apply to services apply to jobs as well.
triggers
triggers defines when the job runs. It's required, and it must set manual or schedule.
manual
triggers.manual sets whether you can start the job with
docker compose run. It's a boolean:
- Not set: you can start the job manually. This is the default.
true: manual invocation is the job's trigger. Use it for a job that has no schedule. Compose rejectsmanual: truetogether withschedule, because the job would then declare two triggers.false: you can't start the job manually.docker compose runfails, including when another job depends on this one. Pair it with aschedule, otherwise the job never runs.
jobs:
rotate-logs:
image: example/rotate
triggers:
manual: false
schedule:
- cron: "0 0 1 * *"schedule
triggers.schedule is a list of schedules on which Docker Engine runs the job.
Compose supports one entry for each job. An entry is either a cron expression
written as a string, or a mapping with the attributes that follow.
The following two jobs have the same schedule:
jobs:
short-syntax:
image: example/job
triggers:
schedule:
- "*/10 * * * *"
long-syntax:
image: example/job
triggers:
schedule:
- cron: "*/10 * * * *"A manual run of a scheduled job is an extra run. It doesn't change the time of the next scheduled run.
Docker Engine parses the cron expression when docker compose up registers the
job, so an invalid expression fails then and not when Compose loads the file. A
second entry fails at the same moment.
cron
cron is required. It's a crontab expression with five fields separated by
spaces: minute, hour, day of the month, month, and day of the week.
| Field | Accepted values |
|---|---|
| Minute | 0-59 |
| Hour | 0-23 |
| Day of month | 1-31 |
| Month | 1-12 |
| Day of week | 0-7, where 0 and 7 are Sunday |
Each field accepts numbers, lists such as 1,15, ranges such as 1-5, and
steps such as */10 or 0-30/10. Names such as mon or jan and shortcuts
such as @daily aren't supported. When both the day of the month and the day
of the week are restricted, the job runs on days that match either field.
timezone
timezone is the IANA time zone name that Docker Engine uses to evaluate
cron, for example Europe/Paris. When it's not set, Docker Engine uses UTC.
concurrency
concurrency sets what happens when the schedule fires while the previous run
of the job is still in progress. The value is one of:
forbidskips the new run. This is the default.queuewaits for the current run to finish and then starts a single new run.
missed_fires
missed_fires sets what happens to runs that were due while Docker Engine was
stopped. The value is one of:
onestarts a single catch-up run when Docker Engine starts again. This is the default.skipdrops the missed runs.
Additional resources
- For a walkthrough, see Run jobs in Compose.
- To turn on jobs in Docker Engine, see Manage jobs in Docker Engine.
- For how jobs interact with profiles, see Profiles.