← all posts

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.

5env vars a Debian cron job started with. DB_HOST wasn't one
#where printenv > /etc/environment cut our value short
10sdocker stop waits on cron as PID 1, then SIGKILLs it

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 the 127.0.0.1 comes from.
  • /usr/local/bin on PATH. The official python, node, php and ruby images install their interpreter there, so python manage.py under cron fails with python: not found.
  • TZ. The job’s timestamps come out in UTC even when the container sets TZ, 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: true or 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 init needed.
  • Stuck with Debian’s cron for now: export -p > /run/cronenv.sh in the entrypoint, . /run/cronenv.sh; and >> /proc/1/fd/1 2>&1 on every line, chmod 0644 on the cron file, and init: true.
  • Alpine image and busybox crond: it already keeps the environment and prints output. Add init: true for the zombies and docker stop.
  • Already running Ofelia across containers: keep it there. Inside one image, prefer Supercronic.
  • You want to know what ran last night after docker logs has 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?
Debian and Ubuntu's cron starts every job with a fresh environment: HOME, LOGNAME, PATH, SHELL and PWD, plus whatever the crontab sets and whatever PAM reads from /etc/environment. Docker's -e, --env-file and compose environment: values only exist in the environment of the container's main process, and cron doesn't pass them on. Alpine's busybox crond does keep them, as do Supercronic, Ofelia's job-local and RunWisp. In our test a Debian cron job saw 5 variables, and DB_HOST wasn't one of them.
Is printenv > /etc/environment a safe fix for cron in Docker?
It works for simple values and breaks the rest. PAM parses /etc/environment with its own rules: in our test a value of abc#def arrived as abc, surrounding quotes were stripped, and a multi-line value kept only its first line. A shell entrypoint also drops variables whose names have a dot, such as spring.profiles.active, before printenv sees them. A safer variant is export -p > /run/cronenv.sh in the entrypoint and '. /run/cronenv.sh;' at the start of each crontab line, which keeps quoting intact. Running a scheduler that inherits the environment avoids the problem altogether.
How do I get cron job output into docker logs?
Append >> /proc/1/fd/1 2>&1 to each crontab line. /proc/1/fd/1 is the stdout of the container's PID 1, which is what docker logs reads. It only works when the job runs as the same user as PID 1, or as root. Without it, Debian cron tries to mail the output, finds no mail program, and throws it away with a message to syslog, which a container doesn't run. Busybox crond, Supercronic, Ofelia and RunWisp (with log_output on) send job output to docker logs without the redirect.
Do I need tini or init: true for cron in Docker?
Usually, yes. A process running as PID 1 ignores SIGTERM unless it installs a handler, so docker stop waits 10 seconds and then SIGKILLs a container running cron -f. Orphaned processes are also reparented to PID 1, and busybox crond and Ofelia don't reap them, so a job that backgrounds a process leaves a zombie on every run. init: true in compose, or docker run --init, puts a small init in front that forwards signals and reaps zombies. Supercronic reaps on its own, and the official RunWisp image already runs under tini.
Supercronic or Ofelia for cron inside a single container?
Supercronic, for a crontab inside one image. It reads a standard crontab, keeps the environment, logs each output line and the exit code to stdout, and reaps zombies as PID 1. Ofelia's job-local works too, but its schedule has a seconds field, it prints a job's output only when the job finishes, it doesn't reap zombies, and its binary is linked against musl, so it only runs in Alpine-based images. Ofelia's strength is job-exec and Docker labels across several containers, which a single Dockerfile doesn't need.
How do I keep a history of cron runs inside a Docker container?
RunWisp, an open-source cron replacement that ships as a single binary, can replace cron in the image. Its jobs inherit the container's environment, it prints their output to docker logs, and it keeps every run's output, exit code and duration under /var/lib/runwisp on a volume, with a web UI and alerts on failure. The limits: its binary is about 32 MB against Supercronic's 15.5 MB, the schedule moves from a crontab to a TOML file, it needs a volume to keep the history across container recreates, it doesn't reap orphaned processes unless you use its official image or init: true, and it coordinates nothing across several hosts or replicas.
  1. 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.

  2. 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.

Get started
GPL 3.0 · no accounts · free to self-host

Start in 30 seconds. Ship on your terms.

A single Go binary. If it doesn't earn the disk space, rm it. No account, no signup, no catch.

Install in 30 seconds
curl -fsSL https://get.runwisp.com | sh