How to Run Cron Jobs with Docker

How to Run Cron Jobs with Docker

Reading time1 min
#Docker#Cron#Automation#DevOps#Linux

How to Run Cron Jobs with Docker

A container runs one main process. When that process is your app, there is no cron daemon around to run scheduled jobs. You can still schedule work for a Dockerized app in three ways, roughly in order of preference:

  1. Let the host (or the orchestrator) schedule a container.
  2. Run a dedicated container whose main process is a scheduler.
  3. Run cron next to the app in the same container.

Option 1: schedule from the host

The host already has cron or systemd timers. Let it start a short-lived container, or run a command in an existing one:

sudo crontab -e
# Run a job image once a night, remove the container afterwards
0 2 * * * /usr/bin/docker run --rm --network my-app_default --env-file /etc/my-app/backup.env my-backup:1.0 >> /var/log/my-backup.log 2>&1

# Run a script inside the running app container every 15 minutes
*/15 * * * * /usr/bin/docker exec my-app /app/bin/cleanup.sh >> /var/log/my-app-cleanup.log 2>&1

Nothing inside the image changes, every run starts clean, and failures show up in the host's logs. The crontab owner must be able to talk to the Docker daemon, which is why the example uses root's crontab.

On Kubernetes use a CronJob, and on ECS use scheduled tasks through EventBridge Scheduler. Both follow the same idea: the platform starts a container on a schedule.

Option 2: a dedicated cron container

When the schedule should live with the app (for example in the same Compose project), build a small image whose only job is to run cron. Debian-based example with four files.

crontab:

SHELL=/bin/sh
0 2 * * * root . /app/container.env; /app/backup.sh >> /proc/1/fd/1 2>&1

backup.sh:

#!/bin/sh
set -eu
echo "$(date -Iseconds) backup started for ${DB_HOST}"
# real work goes here, for example pg_dump to object storage

entrypoint.sh:

#!/bin/sh
set -e
(umask 077 && export -p > /app/container.env)
exec cron -f

Dockerfile:

FROM debian:trixie-slim
RUN apt-get update \
 && apt-get install -y --no-install-recommends cron tzdata \
 && rm -rf /var/lib/apt/lists/*
COPY backup.sh entrypoint.sh /app/
COPY crontab /etc/cron.d/my-app
RUN chmod 0644 /etc/cron.d/my-app && chmod 0755 /app/backup.sh /app/entrypoint.sh
ENTRYPOINT ["/app/entrypoint.sh"]

Build and run it:

docker build -t my-cron:1.0 .
docker run -d --name my-cron -e DB_HOST=db.internal -e TZ=Europe/Berlin my-cron:1.0
docker logs -f my-cron

Each detail in there fixes a common failure:

  • cron -f keeps cron in the foreground as PID 1. If cron forks into the background, the main process exits and the container stops.
  • The environment file. Cron starts jobs with a minimal environment, so variables passed with docker run -e are not visible to the job. The entrypoint saves them with export -p (which quotes values safely) and the job sources the file. The file can contain secrets, hence umask 077.
  • /proc/1/fd/1. Job output written there goes to cron's stdout, which is what docker logs shows. Without it, output is lost because there is no mail or syslog in the container.
  • The /etc/cron.d format. Files there have a user field (root above), must not be writable by group or others, and need a newline after the last line. Debian's cron also ignores files whose names contain a dot, so my-app works and my-app.cron is silently skipped.
  • Timezone. Cron uses the container's local time, which is UTC unless you set TZ and the image has tzdata.

On Alpine, BusyBox crond is already installed. Put the schedule in /etc/crontabs/root (no user field) and run crond -f -l 2 as the main process. The same environment and logging advice applies.

Supercronic

Supercronic is a cron implementation built for containers. It passes the container environment to jobs, logs to stdout and stops cleanly on SIGTERM. The crontab has no user field:

0 2 * * * /app/backup.sh
CMD ["supercronic", "/app/crontab"]

Install the binary from its GitHub releases and verify the published checksum in the Dockerfile. With Supercronic you can drop the entrypoint script and the /proc/1/fd/1 redirects.

In Compose

services:
  app:
    image: my-app:1.0
  cron:
    image: my-cron:1.0
    environment:
      DB_HOST: db
      TZ: Europe/Berlin
    restart: unless-stopped

The cron service can reach other services by name and can be updated or restarted without touching the app.

Option 3: cron inside the app container

Sometimes the job needs the app's code and files and a second image is not worth it. The tempting shortcut is a start script like cron && exec node server.js. It runs, but nothing watches cron: if it dies, jobs stop and the container stays healthy.

If you need both processes, run them under a small supervisor such as supervisord or s6-overlay, which restarts either one and forwards signals. Better still, add the scheduler (Supercronic here) to the app image and run that image as a second service with a different command. The code is identical, only the process differs:

services:
  app:
    image: my-app:1.0
  cron:
    image: my-app:1.0
    command: ["supercronic", "/app/crontab"]

That gives you the convenience of one image without two processes in one container.

Avoid overlapping runs

If a job can take longer than its interval, wrap it with flock so a second run skips instead of piling up:

*/5 * * * * root . /app/container.env; flock -n /tmp/sync.lock /app/sync.sh >> /proc/1/fd/1 2>&1

flock is part of util-linux, present in Debian and Ubuntu images.

Check that it works

docker exec my-cron cat /etc/cron.d/my-app   # file is there and intact
docker exec my-cron date                     # timezone is what you expect
docker logs -f my-cron                       # job output appears here

While testing, use a schedule of * * * * * and watch the logs for a minute. Note that crontab -l shows only the user crontab, not files in /etc/cron.d.

Quick reference

  • Prefer scheduling from outside: host cron or systemd timers with docker run --rm or docker exec, a Kubernetes CronJob, or ECS scheduled tasks.
  • Otherwise, one container with cron as PID 1: cron -f on Debian, crond -f on Alpine, or Supercronic.
  • Pass environment variables explicitly; cron does not inherit them.
  • Send job output to /proc/1/fd/1 so docker logs shows it.
  • /etc/cron.d files: user field, mode 0644, no dot in the name, trailing newline.
  • Set TZ and install tzdata if schedules are not in UTC.
  • Use flock -n for jobs that must not overlap.
    How to Run Cron Jobs with Docker