Console administration

Monitor scheduled Docker jobs

Run and monitor scheduled Docker containers with the WarnFire client.

Use a heartbeat monitor for each scheduled container job. The WarnFire client reports when docker run starts, its exit code, and the combined last 16 KiB of its standard output and standard error. Output also passes through to the host terminal or scheduler log. A line on standard error does not itself mark the run failed. WarnFire uses the monitor’s exit-code set to interpret the numeric code; without a set, 0 succeeds and nonzero codes fail. Avoid printing secrets in job output.

This checks scheduled container runs. It does not watch every running container, Docker health checks, or the Docker daemon. The published docker.io/craigs/warnfire-cli:<release-sha> image contains the client, not the Docker CLI or your job executable. You do not need to mount the Docker socket into that image.

Prepare a monitor and the host

1. In Configuration → Heartbeats → Create, create a monitor for this job. Select the service whose escalation policy should handle a failed or missed run. Set its expected interval, grace period, and maximum run time to match the schedule and workload. Copy its ping URL once.
2. Install the WarnFire client and Docker CLI on the host that schedules the container. Check warnfire version, warnfire job --help, docker version, and the absolute Docker executable path (command -v docker). The scheduling account must already have permission to run Docker. Docker access is powerful; use the account your host administrator has approved for this workload.
3. Save the ping URL in a private regular file owned by that account, for example ~/.config/warnfire/nightly-billing-url with mode 0600. Keep the URL out of shell arguments, Docker image layers, crontabs, and logs.

Use an immutable job image tag or digest that contains the actual workload. Ensure its codes distinguish expected results from failures, and assign a matching set if successful results can be nonzero. docker run must stay attached: do not pass -d, because the Docker CLI would return before the job finished. --rm removes the stopped container after its output and exit status have been observed.

Have the CLI install and maintain the schedule

For a daily 02:00 run on a Linux host, substitute the absolute Docker path printed by command -v docker:

warnfire job install --name nightly-billing --scheduler cron \
  --schedule '0 2 * * *' \
  --url-file "$HOME/.config/warnfire/nightly-billing-url" \
  -- /usr/bin/docker run --rm --name warnfire-nightly-billing \
  registry.example.com/billing-jobs@sha256:<job-image-digest>
warnfire job status nightly-billing

The CLI copies the URL into its managed private file and adds one marked crontab entry for the current account. Reinstalling the same name updates the schedule or Docker command. warnfire job list shows managed jobs; warnfire job remove nightly-billing removes the schedule and managed URL file. It does not remove the heartbeat monitor or its history. On a host that uses systemd user timers, replace --scheduler cron --schedule '0 2 * * *' with --scheduler systemd --schedule '*-*-* 02:00:00'. See the CLI option reference for the exact behavior of install, status, and remove.

To test the wrapper once without adding another schedule, use the same private URL file. This runs the container immediately:

WARNFIRE_HEARTBEAT_CONFIG="$HOME/.config/warnfire/nightly-billing-url" \
  warnfire run -- /usr/bin/docker run --rm \
  registry.example.com/billing-jobs@sha256:<job-image-digest>

The ping URL is not passed to the Docker CLI or the job container. A Docker startup error produces a nonzero code and fails under the standard interpretation. Keep Docker startup-error codes classified as failed in a custom set. The wrapper returns the original Docker exit code to the scheduler regardless of its WarnFire interpretation. Check the host scheduler log for the full output, and Configuration → Heartbeats → History for the run result and bounded diagnostic tail.

Put the client inside your job image

If your scheduler starts a Docker container directly, you can copy the client from the maintained WarnFire image into your own job image. The source image must match your runtime architecture; the published CLI image is Linux amd64. Pin the released image by digest from the signed accepted release manifest:

FROM docker.io/craigs/warnfire-cli@sha256:<cli-image-digest> AS warnfire
FROM registry.example.com/billing-jobs@sha256:<job-image-digest>
COPY --from=warnfire /usr/local/bin/warnfire /usr/local/bin/warnfire
ENTRYPOINT ["/usr/local/bin/warnfire", "run", "--", "/app/my-job"]

Supply WARNFIRE_HEARTBEAT_URL through your scheduler’s secret injection, or mount a private URL file and set WARNFIRE_HEARTBEAT_CONFIG to its path. Set exactly one. The client removes both variables from the child job environment. Do not bake the URL into the image or put it in docker run -e WARNFIRE_HEARTBEAT_URL=<url> on a shared host, because command arguments may be exposed. The scheduler remains responsible for starting this image on time; warnfire run reports one execution, not a recurring schedule.

For Kubernetes CronJobs on EKS, AKS, or GKE, use the Kubernetes guide . Its warnfire job install --scheduler kubernetes command creates and maintains the Secret and CronJob, and copies the client from the maintained image into the workload Pod automatically.