theohbrothers/docker-alpine-cron repository overview

⁠docker-alpine-cron

Dockerized alpine with busybox crond and useful tools.

Packages included for all images: curl, wget

⁠Tags

⁠Usage

Example 1: Create one cron that runs as root

docker run -it \
    -e CRON='* * * * * /bin/echo "hello"' \
    theohbrothers/docker-alpine-cron:3.20

Example 2: Create two crons that run as root

docker run -it \
    -e CRON='* * * * * /bin/echo "hello"\n* * * * * /bin/echo "world"' \
    theohbrothers/docker-alpine-cron:3.20

Example 3: Create two crons that run as UID 3000 and GID 4000

docker run -it \
    -e CRON='* * * * * /bin/echo "hello"\n* * * * * /bin/echo "world"' \
    -e CRON_UID=3000 \
    -e CRON_GID=4000 \
    theohbrothers/docker-alpine-cron:3.20

⁠Environment variables

⁠Entrypoint: docker-entrypoint.sh

1. A /etc/environment file is created at the beginning of the entrypoint script, which makes environment variables available to everyone, including crond.
2. A user of CRON_UID is created if it does not exist.
3. A group of CRON_GID is created if it does not exist.
4. The user of CRON_UID is added to the group of CRON_GID if membership does not exist.
5. Crontab is created in /etc/crontabs/<CRON_USER>

⁠Secrets

Since a /etc/environment file is created automatically to make environment variables available to every cron, any sensitive environment variables will get written to the disk. To avoid that:

1. Add shell functions like this⁠ at the beginning of your cron-called script
2. Optional: Specify the secrets folder by using environment variable ENV_SECRETS_DIR. By default, its value is /run/secrets
3. Declare environment variables using syntax MY_ENV_VAR=DOCKER-SECRET:my_docker_secret_name, where my_docker_secret_name is the secret mounted on $ENV_SECRETS_DIR/my_docker_secret_name
4. When the cron script is run, the env var MY_ENV_VAR gets populated with the contents of the secret file $ENV_SECRETS_DIR/my_docker_secret_name

⁠FAQ

⁠Q: Why use a cron container?

This image is only needed if there is no container orchestrator (E.g. Docker in standalone mode), or if there is a container orchestrator but without a cron scheduler (E.g. Docker in Swarm mode).

If your orchestrator already provides an external scheduler (E.g. Kubernetes via CronJob), there's no need to use this image.

⁠Q: Why use CRON environment variable? Just use crontab -

Right. If the cron command is complex, and there is no need for customizing CRON_UID and CRON_GID, it is better to skip this image altogether and simply write everything in the entrypoint of the container manifest. For example, in Compose:

version: '2.2'
services:
  some-cron:
    image: alpine
    tty: true
    entrypoint:
      - /bin/sh
    command:
      - -c
      - |
          set -eu

          crontab - <<'EOF'
          * * * * * /bin/echo "My super 'complex' cron command with quotes is better written in shell"
          EOF

          exec crond -f

⁠Q: My cron is not running!

• Use docker logs to check whether crond has spit out any messages about the syntax of your cron
• If bind-mouting your own crontab in /etc/crontabs, ensure:
  • the crontab is owned by root:root with 0600 permissions. See here⁠
  • the crontab has a newline at the end of the file

⁠Development

Requires Windows powershell or pwsh⁠.

# Install Generate-DockerImageVariants module: https://github.com/theohbrothers/Generate-DockerImageVariants
Install-Module -Name Generate-DockerImageVariants -Repository PSGallery -Scope CurrentUser -Force -Verbose

# Edit ./generate templates

# Generate the variants
Generate-DockerImageVariants .