Cron in a Docker container: missing env vars, empty docker logs, and Supercronic vs Ofelia
Your job works with docker exec and fails under cron: DB_HOST is empty, python isn't found, and docker logs shows nothing. What cron does to the environment, why printenv > /etc/environment cuts values at #, the PID 1 and zombie problem, and Supercronic vs Ofelia vs RunWisp in one image.
12 min read
The job works when you run it by hand:
$ docker exec app /app/bin/nightly-report.sh
report: 1,204 orders, sent to [email protected]
So you add a crontab line to the image, and the next morning there’s no report. docker logs app
is empty. When you finally get the job to print something, it says it couldn’t connect to the
database at 127.0.0.1, or that python: not found, in a container where python obviously
exists.
The usual answers are printenv > /etc/environment in the entrypoint and > /proc/1/fd/1 on the
crontab line. They partly work. We ran the same job under five schedulers in one container each and
checked four things: whether the job sees the container’s environment, whether its output reaches
docker logs, whether the failure is logged, and what happens at PID 1.
This post is about one Dockerfile with cron in it. If the scheduler is a separate service in a compose stack, Docker Compose cron jobs with a web UI covers that.
Short answer
Debian and Ubuntu’s cron starts each job with an empty environment and mails its output, and a
container has no mail. The printenv > /etc/environment fix mangles values containing #, quotes
or newlines. Replace cron in the image with a scheduler built for containers. Supercronic is the
smallest: it reads your crontab, keeps the environment, logs each line and the exit code to stdout,
and reaps zombies. Ofelia is a weaker fit inside one image: musl-only binary, output printed
only when the job ends, no zombie reaping. If you also want each run’s output and exit code kept
after docker logs rotates, plus alerts, use RunWisp, an open-source cron replacement that
ships as a single binary. Whatever you pick, add init: true unless the scheduler reaps
orphaned processes itself.
We tested with Podman 5.7, which runs OCI images the way Docker does: debian:trixie-slim with cron
3.0pl1-197, alpine:3.22 with busybox crond, Supercronic 0.2.51, mcuadros/ofelia:latest (April
2026 build) and RunWisp 1.7.1. Each container got the same --env-file, ran the same script every
minute, and the script left an orphaned sleep behind on purpose.
| Job sees container env | Job output in docker logs |
Exit code logged | Reaps zombies as PID 1 | Exits on docker stop |
|
|---|---|---|---|---|---|
| Debian cron | ✗ | ✗ | ✗ | ✓ | ✗ |
| Alpine busybox crond | ✓ | ✓ | ✗ | ✗ | ✗ |
| Supercronic | ✓ | ✓ | ✓ | ✓ | ✓ |
Ofelia job-local |
✓ | after job ends | ✓ | ✗ | ✓ |
| RunWisp (official image) | ✓ | ✓ | ✓ | ✓ (via tini) | ✓ |
“Exits on docker stop” is with the scheduler as PID 1 and no init: true. With an init in front,
every row exits at once. Only RunWisp keeps the runs after the log rotates, and it’s also the biggest
binary here: 32 MB, against 15.5 MB for Supercronic and 14.8 MB for Ofelia.
Why the job can’t see your env vars
When you pass -e DB_HOST=db or an environment: block in compose, Docker puts those variables in
the environment of the container’s main process, and only there. Child processes get them by
inheriting. Debian’s cron doesn’t let them through: it builds each job’s environment from scratch.
Here is everything our job saw, with seven variables of our own set on the container:
HOME=/root
LOGNAME=root
PATH=/usr/bin:/bin
SHELL=/bin/sh
PWD=/root
Three things go missing here, and each causes a different error:
- Your app config.
DB_HOST,DATABASE_URL, API keys. The app falls back to its defaults, which is where the127.0.0.1comes from. /usr/local/binonPATH. The officialpython,node,phpandrubyimages install their interpreter there, sopython manage.pyunder cron fails withpython: not found.TZ. The job’s timestamps come out in UTC even when the container setsTZ, unless the image also sets/etc/localtime.
Alpine’s busybox crond is different. It keeps the environment it was started with and only
sets HOME, SHELL, USER and LOGNAME on top, so the same job on alpine:3.22 saw every
variable. If your image is Alpine-based and plain crond works, that’s why.
The printenv > /etc/environment fix, and where it breaks
The popular fix dumps the container’s environment into /etc/environment at startup, because
Debian’s cron runs each job through PAM, and PAM’s pam_env reads that file:
#!/bin/sh
# entrypoint.sh
printenv > /etc/environment
exec cron -f
It works for DB_HOST=db. pam_env parses the file with its own rules, though, and isn’t a shell.
We passed these values to the container and printed what the cron job got:
value set on the container what the cron job saw
HASH=abc#def HASH=abc
SINGLE='quoted' SINGLE=quoted
DOUBLE="quoted" DOUBLE=quoted
MULTI=line1\nline2 (two lines) MULTI=line1
spring.profiles.active=prod (missing)
A # starts a comment, so a password like hunter2#prod arrives as hunter2, and you get an
authentication error instead of a parsing one. Surrounding quotes are eaten. A PEM key or any other
multi-line value keeps its first line. The dotted name never made it into the file at all: the
entrypoint is a /bin/sh script, and dash drops variables whose names aren’t valid shell names
before printenv runs. The file is also world-readable (-rw-r--r--), so every secret in it is
readable by any user in the container.
It also doesn’t fix PATH: Debian’s cron sets PATH=/usr/bin:/bin itself and ignores the one in
/etc/environment, so python: not found stays.
A variant that keeps the values intact is a shell snapshot. export -p prints every variable
quoted so the shell can read it back:
#!/bin/sh
# entrypoint.sh
export -p > /run/cronenv.sh
chmod 600 /run/cronenv.sh
exec cron -f
# /etc/cron.d/report (mode 644, see below)
0 6 * * * root . /run/cronenv.sh; /app/bin/nightly-report.sh >> /proc/1/fd/1 2>&1
With that, abc#def, the quotes and the two-line value all arrived unchanged, and so did PATH:
the job saw /usr/local/bin again, which /etc/environment doesn’t give you. Dotted names are
still lost, and you have to remember the prefix on every line. At that point you’re maintaining
glue code to make cron behave like a scheduler that keeps the environment, and several exist.
Why the output goes nowhere
cron was built for multi-user machines with a local mail system: whatever a job prints is mailed to
its owner. A container has no mail program, so Debian’s cron logs “No MTA installed, discarding
output” to syslog, and a container doesn’t run syslog either. The output and the complaint both
disappear. cron itself prints nothing to docker logs, so you can’t even tell whether the job ran.
The fix is a redirect on every line:
* * * * * root /app/bin/job.sh >> /proc/1/fd/1 2>&1
/proc/1/fd/1 is the stdout of PID 1, which is what docker logs reads. /dev/stdout doesn’t
work here, because it refers to the job’s own stdout, which cron has captured. The redirect only
works if the job runs as the same user as PID 1, or as root. You get the job’s lines with no
timestamp, no job name and no exit code: a failed run that printed nothing looks exactly like a
successful run that printed nothing.
One more silent failure we ran into while testing: Debian’s cron skips a file in /etc/cron.d
that is group-writable. Our crontab was created with a umask of 002, mode 664, and cron
ignored it without a word in docker logs, because the “INSECURE MODE” warning also goes to
syslog. If you COPY cron files from a checkout, add chmod 0644 in the Dockerfile.
The PID 1 problem
Whatever you put in CMD runs as PID 1, and PID 1 has two jobs a normal process doesn’t.
It ignores signals it doesn’t handle. The kernel doesn’t apply default signal actions to PID 1,
so SIGTERM does nothing unless the process installs a handler. docker stop sends SIGTERM, waits
10 seconds, and then sends SIGKILL. Debian’s cron -f and busybox crond -f both sat through the
full 10 seconds and exited with 137. Supercronic, Ofelia and RunWisp handle SIGTERM and exited in
under half a second.
It inherits every orphan. When a job starts a background process and exits, that process is
reparented to PID 1. When it finishes, PID 1 has to wait() on it, or it stays in the process table
as a zombie. Our test script left one sleep behind per run. A minute later:
busybox crond as PID 1 Debian cron as PID 1
PID PPID STAT COMMAND PID PPID STAT COMMAND
1 0 S crond 1 0 Ss cron
8 1 Z sleep
15 1 Z sleep
Debian’s cron reaps any child it gets, so it stayed clean. Busybox crond and Ofelia don’t, and
collected one zombie per run. RunWisp doesn’t either, which is why its official image starts it under
tini. Supercronic forks itself when it’s PID 1 and the parent reaps.
A zombie costs a PID and no memory, so a few are harmless. It becomes a problem when a job leaks
one every minute for months, or when the container has a pids_limit. The fix for both signal
handling and reaping is one line in compose:
services:
cron:
image: my/app
init: true
init: true (or docker run --init) runs Docker’s bundled tini as PID 1. It forwards SIGTERM to
your process and reaps orphans. With it, Debian cron and busybox crond both exited at once on
docker stop. A job that’s running when the container stops still gets killed, unless the
scheduler waits for it. Laravel scheduler in Docker has the
measurements for that case.
Supercronic vs Ofelia vs RunWisp in the image
All three keep the environment and handle SIGTERM. The test job printed a line to stdout, a
pg_dump error to stderr, and exited 3.
Supercronic
Supercronic is a crontab runner written for containers. It reads a standard five-field crontab (no user column) and runs everything as the container’s user:
FROM python:3.13-slim
ADD --chmod=755 https://github.com/aptible/supercronic/releases/download/v0.2.51/supercronic-linux-amd64 /usr/local/bin/supercronic
COPY crontab /app/crontab
CMD ["supercronic", "/app/crontab"]
What docker logs showed for the failed run (fields trimmed):
level=info msg=starting job.command=/fail.sh job.schedule="* * * * *"
level=info msg="dumping app db" channel=stdout
level=info msg="pg_dump: error: connection to server at \"db\" failed: Connection refused" channel=stderr
level=error msg="error running command: exit status 3"
Each line is tagged with its stream, the exit code is logged, and -json turns it all into JSON
for Loki or Datadog. It reaps zombies and waits for running jobs on SIGTERM. There’s no timeout,
no retry and no history: once the log rotates, the run is gone. Its only built-in alerting is Sentry,
though it also exposes Prometheus metrics. For a crontab and stdout, it’s the right size.
RunWisp vs Supercronic goes through it in more detail.
Ofelia job-local
Ofelia is mostly used as a separate container that schedules
docker exec into others through Docker labels. Its job-local type runs a command in its own
container, which is the single-image case:
; /etc/ofelia/config.ini
[job-local "backup"]
schedule = 0 0 3 * * *
command = /app/bin/backup.sh
Note the six fields: Ofelia’s schedule starts with seconds, so 0 3 * * * copied from a crontab
means something else. The failed run looked like this:
[Job "backup" (a48bf6de10f0)] Started - /fail.sh
[Job "backup" (a48bf6de10f0)] StdOut: dumping app db
[Job "backup" (a48bf6de10f0)] StdErr: pg_dump: error: connection to server at "db" failed: Connection refused
[Job "backup" (a48bf6de10f0)] Finished in "459.338µs", failed: true, skipped: false, error: exit status 3
Good output once it arrives. Ofelia buffers it and prints it all when the job ends, so a 40-minute
job shows nothing for 40 minutes. It doesn’t reap zombies, so it needs init: true. And you can’t
just copy its binary into your image: the one in mcuadros/ofelia is linked against musl, and in a
Debian-based image it fails with not found or no such file or directory. It works if your app image is Alpine-based.
Inside a single image, Ofelia adds nothing over Supercronic. Its strength is labels across
containers, which RunWisp vs Ofelia compares.
RunWisp
RunWisp (our project, so weigh accordingly) is an open-source cron replacement that ships as a single binary, with a web UI that records every run’s output, exit code and duration. Copy the binary into the app image:
FROM python:3.13-slim
COPY --from=runwisp/runwisp:1 /usr/local/bin/runwisp /usr/local/bin/runwisp
COPY runwisp.toml /etc/runwisp/runwisp.toml
ENV RUNWISP_LOG_OUTPUT=true
CMD ["runwisp", "daemon"]
# runwisp.toml
[tasks.nightly-report]
cron = "0 6 * * *"
run = "/app/bin/nightly-report.sh"
timeout = "15m"
notify = ["slack-ops"]
[notifiers.slack-ops]
type = "slack"
webhook_url = "${SLACK_OPS_URL}"
Tasks inherit the container’s environment, the same as running the command with docker exec.
RUNWISP_LOG_OUTPUT=true prints each output line to docker logs with the task name in front:
[INFO] run started task=nightly-report run=01M5WG0E30X5W330XEENAFP40J
nightly-report | dumping app db
nightly-report | pg_dump: error: connection to server at "db" failed: Connection refused
[WARN] run failed task=nightly-report run=01M5WG0E30X5W330XEENAFP40J exit=3 reason=failed dur=36ms
Runs and their output are also stored under /var/lib/runwisp, so put a volume there.
docker compose exec cron runwisp logs nightly-report prints past runs after docker logs has rotated, and the web
UI on port 9477 lists them. A failed run can alert you on Slack, Discord, Telegram, email or a
webhook, with the last lines of output in the message. In compose:
services:
cron:
build: .
init: true # RunWisp doesn't reap orphans itself
environment:
RUNWISP_PASSWORD: change-me
RUNWISP_HOST: 0.0.0.0 # only needed for the web UI
ports: ["127.0.0.1:9477:9477"]
volumes: [runwisp-data:/var/lib/runwisp]
volumes:
runwisp-data:
For an image that exists only to run jobs (restic, curl, a backup script), start from the
official image instead: FROM runwisp/runwisp:1, then apk add your tools. It already runs under
tini with RUNWISP_LOG_OUTPUT=true, so you can drop init: true.
Running in Docker covers both.
To move an existing crontab, runwisp import cron crontab -o runwisp.toml converts it, and
runwisp import ofelia config.ini does the same for Ofelia. One catch in a container: the cron
importer writes env_base = "clean" on every task, which copies cron’s empty environment on
purpose. Delete those lines, or your tasks lose DB_HOST again.
The limits, honestly:
- It’s bigger. 32 MB of binary, plus a data volume and optionally a port, where Supercronic is 15.5 MB and needs neither.
- The schedule moves to TOML. Your crontab doesn’t run as-is, though the importer does the conversion.
- Without the volume, history goes with the container. A plain container recreate wipes it.
- It doesn’t reap orphans itself. Use
init: trueor the official image. - One container, one scheduler. Run three replicas of the image and every task runs three
times. Like everything above, it has no leader election. On Kubernetes, use a
CronJob.
Which one to use
- A crontab, and stdout is enough: Supercronic, with no
initneeded. - Stuck with Debian’s cron for now:
export -p > /run/cronenv.shin the entrypoint,. /run/cronenv.sh;and>> /proc/1/fd/1 2>&1on every line,chmod 0644on the cron file, andinit: true. - Alpine image and busybox crond: it already keeps the environment and prints output. Add
init: truefor the zombies anddocker stop. - Already running Ofelia across containers: keep it there. Inside one image, prefer Supercronic.
- You want to know what ran last night after
docker logshas rotated, and hear about failures without wiring Sentry: RunWisp. The quick start has the non-Docker install, cron logs covers the same problem outside containers, and the code is on GitHub.
Common questions
Why can't my cron job see the Docker container's environment variables?
Is printenv > /etc/environment a safe fix for cron in Docker?
How do I get cron job output into docker logs?
Do I need tini or init: true for cron in Docker?
Supercronic or Ofelia for cron inside a single container?
How do I keep a history of cron runs inside a Docker container?
Read next
-
Missed cron jobs after shutdown or suspend: anacron vs systemd Persistent= vs catch-up
What cron, anacron, systemd timers and RunWisp do with a run that was due while the machine was off or asleep, including cron's 3-hour rule and anacron's AC-power check, plus a test you can run in five minutes.
-
Run cron jobs as a non-root user in Docker, without setuid
USER app doesn't make Debian cron an unprivileged scheduler. Two complete setups with Supercronic or RunWisp, plus the UID, config and writable-volume checks that stop permission errors.