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:
- Let the host (or the orchestrator) schedule a container.
- Run a dedicated container whose main process is a scheduler.
- 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 -fkeeps 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 -eare not visible to the job. The entrypoint saves them withexport -p(which quotes values safely) and the job sources the file. The file can contain secrets, henceumask 077. /proc/1/fd/1. Job output written there goes to cron's stdout, which is whatdocker logsshows. Without it, output is lost because there is no mail or syslog in the container.- The
/etc/cron.dformat. Files there have a user field (rootabove), 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, somy-appworks andmy-app.cronis silently skipped. - Timezone. Cron uses the container's local time, which is UTC unless you set
TZand the image hastzdata.
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 --rmordocker exec, a KubernetesCronJob, or ECS scheduled tasks. - Otherwise, one container with cron as PID 1:
cron -fon Debian,crond -fon Alpine, or Supercronic. - Pass environment variables explicitly; cron does not inherit them.
- Send job output to
/proc/1/fd/1sodocker logsshows it. /etc/cron.dfiles: user field, mode 0644, no dot in the name, trailing newline.- Set
TZand installtzdataif schedules are not in UTC. - Use
flock -nfor jobs that must not overlap.
