docker_scheduler is a simple task scheduler for Docker containers. It executes scheduled (cron) tasks directly inside containers based on Docker labels — no external orchestrator or scheduler required.
You can assign special scheduler labels to your containers. The scheduler container will read these labels and execute the defined commands at the specified times.
How it works:
- When the scheduler starts, it connects to the Docker daemon — via the local socket by default, or via a remote host if
DOCKER_HOSTis set. - Then it reads the labels of all running containers. If any containers define scheduler labels, it registers the corresponding jobs in memory and executes them according to their schedule — similar to a traditional cron.
- The scheduler listens to docker events. Whenever a container is started, stopped, or updated, the scheduler re-evaluates its configuration and updates the active jobs accordingly.
It is inspired by Ofelia. It is great project, but it has one big disadvantage for me - it needs to be restarted when applying changes in labels (at this time 5/2025). So I decided to write my own.
If you just want to use the tool, you can pull the ready-to-use image from Docker Hub:
Standalone
docker run -d \
-v /var/run/docker.sock:/var/run/docker.sock:ro \
-e TZ=Europe/Prague \
lukaskaplan/docker-scheduler... via docker compose
services:
scheduler:
image: lukaskaplan/docker-scheduler
volumes:
- /var/run/docker.sock:/var/run/docker.sock:ro
environment:
TZ: Europe/PragueIf the Docker daemon is running on a remote machine, set DOCKER_HOST instead of mounting the socket.
The following environment variables are supported (same as the Docker CLI, powered by docker.from_env()):
| Variable | Description |
|---|---|
DOCKER_HOST |
URL to the Docker host (e.g. tcp://remote-host:2375) |
DOCKER_TLS_VERIFY |
Verify the host against a CA certificate |
DOCKER_CERT_PATH |
Path to a directory containing TLS certificates |
Standalone
docker run -d \
-e DOCKER_HOST=tcp://remote-host:2375 \
-e TZ=Europe/Prague \
lukaskaplan/docker-scheduler... via docker compose
services:
scheduler:
image: lukaskaplan/docker-scheduler
environment:
DOCKER_HOST: tcp://remote-host:2375
TZ: Europe/PragueRun docker compose up -d
- Run docker_scheduler:
(As shown above.)
- Label your containers with cron expressions:
- Each container can define one or more jobs via labels.
- Each job must have a unique name (for this one container).
Example:
services:
your_container:
image: your-image
labels:
# Turn on scheduler for this container:
scheduler.enable: "true"
# Replace <job-name> be name of the job:
scheduler.<job-name>.schedule: "*/2 * * * *"
scheduler.<job-name>.command: "echo Hello World!"
# You can define multiple jobs:
scheduler.backup.schedule: "0 2 * * *"
scheduler.backup.command: "pg_dumpall -U postgres > /backup/db.sql"
scheduler.cleanup.schedule: "0 4 * * *"
scheduler.cleanup.command: "rm -rf /tmp/*"- Check logs:
docker logs -f <docker_scheduler_container_id>If you want to contribute or run the scheduler locally:
- Clone the repo:
git clone https://github.com/lukaskaplan/docker_scheduler.git
cd docker_scheduler- Create and activate a virtual environment:
python3 -m venv venv
source venv/bin/activate- Install dependencies:
pip install -r requirements.txt- Build the Docker container:
docker build . -t docker_scheduler- Run the scheduler:
docker run -it --rm -v /var/run/docker.sock:/var/run/docker.sock:ro -e TZ=Europe/Prague docker_schedulerEnsure the Docker daemon is running and the socket is accessible.
Official Docker image: https://hub.docker.com/r/lukaskaplan/docker-scheduler
This project is licensed under the MIT License. See LICENSE for details.
Contributions are welcome! If you have suggestions, issues, or ideas, please open an issue or pull request.