Docker Compose v5.8.0 adds a top-level jobs: element: containers that run to completion, on demand or on a schedule, declared next to the services they work with. A nightly database backup no longer needs a cron entry on the host or a container running crond. It lives in the Compose file, and the Docker Engine fires it.
Because the engine owns the schedule, a job keeps firing after the docker compose command has exited, and also when the project targets a remote engine. Each execution is recorded with its state and exit code.
Jobs are experimental: the Compose file syntax and the behavior may change between releases. Scheduling needs Docker Engine 29.10 or later with the jobs extension enabled, which is off by default. Jobs that are only run on demand work without it.
Enable the extension
dockerd --extension-enable org.mobyproject.jobs.v0
Or in daemon.json:
{
"extensions": {
"enable": ["org.mobyproject.jobs.v0"]
}
}
The nested form is required. A flat "extension-enable" key in daemon.json is rejected at startup.
A nightly backup
This project runs PostgreSQL and dumps the database every day at 03:00 Paris time:
services:
db:
image: postgres:17
environment:
POSTGRES_PASSWORD: example
healthcheck:
test: ["CMD-SHELL", "pg_isready -U postgres"]
volumes:
- db-data:/var/lib/postgresql/data
- backups:/backups:ro
jobs:
backup:
image: postgres:17
depends_on:
db:
condition: service_healthy
environment:
PGHOST: db
PGUSER: postgres
PGPASSWORD: example
command: sh -c 'pg_dump --format=custom --file=/backups/shop-$$(date +%Y%m%d-%H%M%S).dump postgres'
volumes:
- backups:/backups
triggers:
schedule:
- cron: "0 3 * * *"
timezone: Europe/Paris
volumes:
db-data:
backups:
A job takes the same container attributes as a service: image, command, environment, volumes, networks, depends_on. What it adds is triggers, which is required. Here the job joins the project network, so it reaches the database as db, and the dumps land in the backups volume. That volume is also mounted read-only on db, so the files can be listed from there with docker compose exec db ls /backups.
Register, run, remove
docker compose up registers the job with the engine, which then fires it on its own clock:
$ docker compose up -d
Container shop-db-1 Started
Job backup Creating
Job backup Created
Running up again on an unchanged project does nothing. If the job definition changed, up refuses and says what to do: job "backup" has changed: run docker compose down to remove it, then up again. docker compose down removes the registered job.
A job can also run right now:
$ docker compose run backup
The dependencies start first, and the command waits for db to be healthy. The job’s logs are streamed and its exit code is returned, which makes this the way to take a dump before a migration. A succeeded run returns 0, a failed one the container’s exit code, a timeout 124 and a cancellation 130.
A scheduled job runs exactly as it was registered, so docker compose run refuses options that would change it, such as -e, -v or --user.
Triggers
schedule is a list, and each entry is either a cron string or an object:
cron: a five-field expression.timezone: an IANA timezone such asEurope/Paris, used to evaluate the expression. Without it, the engine uses UTC.concurrency:forbid(default) skips a fire while the previous run is still going,queuedefers it until the run ends.missed_fires:one(default) starts a single catch-up run after the engine was down across fires,skipdrops them.
Setting manual: false under triggers forbids docker compose run for a job that should only run on its schedule.
Pro tip
A few behaviors are worth knowing before relying on a backup job:
- Pipes hide failures.
pg_dump | gzip > fileexits with the status ofgzip. With the database stopped, the run still ended assucceeded. Writing withpg_dump --file, as above, makes a failed dump a failed run. - Successful runs leave no container. Compose registers jobs so that the container of a succeeded run is removed, which is why the example writes to a volume. The container of a failed run is kept and listed by
docker compose ps -awith itsExited (1)status. Its output is still there:docker logs <container>. It lives as long as the run record, and Compose keeps the last 5 runs of a job.docker compose downleaves these containers, anddocker compose down --remove-orphansremoves them. - Dependencies are not started on a schedule.
depends_onis honored bydocker compose run. When the engine fires the job at 03:00,dbhas to be running already. - Deleting a job from the file does not unregister it. The engine keeps the registered job and it keeps firing.
docker compose upwarns about it, anddocker compose up --remove-orphansremoves it. - Not for work a service waits on. A service cannot
depends_ona job. A migration that must finish before the application starts belongs in an init container. - Without the extension,
uprefuses. A project with a scheduled job is rejected before anything is created, with a message that points at the--extension-enableflag.docker compose runon a job falls back to a one-off container.
What’s next: the docker job commands
A succeeded scheduled run leaves no container, so Compose has nothing to list for it. A docker job command group is in review in docker/cli#7503 to list jobs and their runs. It is not part of Docker 29.10, and the UX is not final: names, flags and output may change before it is merged. With a build of that pull request, the jobs registered by Compose appear as <project>.<job>:
$ docker job runs shop.backup
ITERATION STATE EXIT TRIGGER STARTED FINISHED CONTAINER
32 succeeded 0 schedule 37 seconds ago 37 seconds ago 73bf25b1c5c5
31 succeeded 0 schedule About a minute ago About a minute ago 8bd82df7de80
30 succeeded 0 schedule 2 minutes ago 2 minutes ago 2376894b965e