{"id":19435299,"url":"https://github.com/premoweb/chadburn","last_synced_at":"2025-03-22T15:46:01.664Z","repository":{"id":37008233,"uuid":"412601155","full_name":"PremoWeb/chadburn","owner":"PremoWeb","description":"Chadburn is a scheduler alternative to cron, built on Go and designed for Docker environments.","archived":false,"fork":false,"pushed_at":"2025-03-14T16:35:51.000Z","size":249,"stargazers_count":38,"open_issues_count":3,"forks_count":4,"subscribers_count":2,"default_branch":"main","last_synced_at":"2025-03-14T16:40:31.351Z","etag":null,"topics":["cron","docker"],"latest_commit_sha":null,"homepage":"","language":"Go","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/PremoWeb.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2021-10-01T19:56:12.000Z","updated_at":"2025-03-14T16:35:55.000Z","dependencies_parsed_at":"2023-12-25T21:09:33.411Z","dependency_job_id":"f2c3fc90-9901-4708-a9b0-3e4f0aeb42d3","html_url":"https://github.com/PremoWeb/chadburn","commit_stats":null,"previous_names":["premoweb/chronos","premoweb/chadburn","maietta/chadburn"],"tags_count":41,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/PremoWeb%2Fchadburn","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/PremoWeb%2Fchadburn/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/PremoWeb%2Fchadburn/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/PremoWeb%2Fchadburn/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/PremoWeb","download_url":"https://codeload.github.com/PremoWeb/chadburn/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":244981293,"owners_count":20542288,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["cron","docker"],"created_at":"2024-11-10T15:05:21.589Z","updated_at":"2025-03-22T15:46:01.658Z","avatar_url":"https://github.com/PremoWeb.png","language":"Go","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Chadburn: A Modern Job Scheduler\n\n[![GitHub release](https://img.shields.io/github/v/release/PremoWeb/Chadburn)](https://github.com/PremoWeb/Chadburn/releases)\n[![Testing Status](https://github.com/PremoWeb/Chadburn/workflows/Testing%20Status/badge.svg)](https://github.com/PremoWeb/Chadburn/actions?query=workflow%3A%22Testing+Status%22)\n[![Docker Pulls](https://img.shields.io/docker/pulls/premoweb/chadburn)](https://hub.docker.com/r/premoweb/chadburn)\n[![Docker Image Size](https://img.shields.io/docker/image-size/premoweb/chadburn/latest)](https://hub.docker.com/r/premoweb/chadburn)\n[![License](https://img.shields.io/github/license/PremoWeb/Chadburn)](https://github.com/PremoWeb/Chadburn/blob/main/LICENSE)\n\n\u003e ### 📣 **NEW!** Visit our dedicated website at [https://chadburn.dev](https://chadburn.dev) for comprehensive documentation, tutorials, and examples. Our documentation is now powered by SvelteKit and hosted on Cloudflare Pages for improved performance and reliability.\n\n**Chadburn** is a lightweight job scheduler designed for __Docker__ environments, developed in Go. It serves as a contemporary replacement for the traditional [cron](https://en.wikipedia.org/wiki/Cron). Chadburn uses semantic versioning and automatic releases based on commit messages. Commit messages are validated using Git hooks to ensure they follow the Conventional Commits format.\n\n---\n\n### Special Note\n\nChadburn is a project built upon the ongoing development from Ofelia, a fork initiated by @rdelcorro. This project was created to address specific needs, including:\n\n- Automatic task updates when Docker containers are started, stopped, restarted, or modified.\n- Elimination of the need for a dummy task in the Chadburn container.\n- Concurrent support for both INI files and Docker labels, allowing configurations to be merged seamlessly.\n- The ability to recognize new tasks or remove existing ones without needing a restart.\n\n---\n\n### Why Choose Chadburn?\n\nSince the release of [`cron`](https://en.wikipedia.org/wiki/Cron) by AT\u0026T Bell Laboratories in March 1975, much has changed in the computing landscape, especially with the rise of Docker. While **Vixie's cron** remains functional, it lacks extensibility and can be challenging to debug when issues arise.\n\nVarious solutions exist, including containerized cron implementations and command wrappers, but these often complicate straightforward tasks.\n\n---\n\n### Important Update: Migration to Official Docker Client\n\nChadburn has removed all references to the legacy polyfill dependency `fsouza/go-dockerclient` and migrated to the official Docker client library. This change brings improved compatibility with the latest Docker features and better long-term maintainability.\n\nWe would like to express our sincere gratitude to Francisco Souza and all contributors to the `fsouza/go-dockerclient` library. Their exceptional work provided a robust foundation for Chadburn and many other Docker-related projects over the years. The library's reliability and comprehensive API coverage were instrumental in Chadburn's early development and success.\n\n---\n\n### Key Features\n\nChadburn's primary feature is its ability to execute commands directly within Docker containers. Utilizing Docker's API, Chadburn mimics the behavior of [`exec`](https://docs.docker.com/reference/commandline/exec/), enabling commands to run inside active containers. Additionally, it allows for command execution in new containers, which are destroyed after use.\n\nChadburn also supports variable substitution in job commands, allowing you to reference container information dynamically using syntax like `{{.Container.Name}}` and `{{.Container.ID}}`. This makes it easier to create reusable job configurations that can interact with containers without hardcoding their names or IDs.\n\n---\n\n## Configuration\n\nFor the most comprehensive and up-to-date documentation, please visit our dedicated website at [https://chadburn.dev](https://chadburn.dev).\n\nA comprehensive wiki is underway to detail Chadburn's usage. Caprover users will soon have access to a One Click App for deploying and managing scheduled jobs via Service Label Overrides.\n\nFor others, here's a quick guide to get started with Chadburn:\n\n### Job Scheduling\n\nChadburn uses a scheduling format consistent with the Go implementation of `cron`. Examples include `@every 10s` or `0 0 1 * * *` (which runs every night at 1 AM).\n\n**Note**: The scheduling format previously included seconds; however, this has been updated in the latest version of Chadburn. Significant development is planned to resolve various issues reported with both Ofelia and Chadburn.\n\nYou can configure four types of jobs:\n\n- `job-exec`: Executes a command inside a running container.\n- `job-run`: Runs a command in a new container using a specified image.\n- `job-local`: Executes a command on the host running Chadburn.\n- `job-service-run`: Runs a command inside a new \"run-once\" service for swarm environments.\n\nFor detailed parameters, refer to the [Jobs reference documentation](https://chadburn.dev/jobs).\n\n#### INI Configuration\n\nTo run Chadburn with an INI file, use the command:\n\n```bash\nchadburn daemon --config=/path/to/config.ini\n```\n\nHere's a sample INI configuration:\n\n```ini\n[job-exec \"job-executed-on-running-container\"]\nschedule = @hourly\ncontainer = my-container\ncommand = touch /tmp/example\n\n[job-run \"job-executed-on-new-container\"]\nschedule = @hourly\nimage = ubuntu:latest\ncommand = touch /tmp/example\n\n[job-local \"job-executed-on-current-host\"]\nschedule = @hourly\ncommand = touch /tmp/example\n\n[job-service-run \"service-executed-on-new-container\"]\nschedule = 0,20,40 * * * *\nimage = ubuntu\nnetwork = swarm_network\ncommand = touch /tmp/example\n```\n\n#### Docker Label Configurations\n\nFor Docker label configurations, Chadburn needs access to the Docker socket:\n\n```bash\ndocker run -it --rm \\\n    -v /var/run/docker.sock:/var/run/docker.sock:ro \\\n    premoweb/chadburn:latest daemon\n```\n\n\u003e **Note**: If you encounter permission issues with the Docker socket, refer to our [Docker Socket Permissions Guide](https://chadburn.dev/docker-socket-permissions) for solutions.\n\nThe labels format is: `chadburn.\u003cJOB_TYPE\u003e.\u003cJOB_NAME\u003e.\u003cJOB_PARAMETER\u003e=\u003cPARAMETER_VALUE\u003e`. This configuration method supports all capabilities provided by INI files.\n\nTo execute `job-exec`, the target container must have the label `chadburn.enabled=true`.\n\nFor example, to run the `uname -a` command in an existing container called `my_nginx`, start `my_nginx` with the following configurations:\n\n```bash\ndocker run -it --rm \\\n    --label chadburn.enabled=true \\\n    --label chadburn.job-exec.test-exec-job.schedule=\"@every 5s\" \\\n    --label chadburn.job-exec.test-exec-job.command=\"uname -a\" \\\n    nginx\n```\n\nAlternatively, you can use Docker Compose:\n\n```yaml\nversion: \"3\"\nservices:\n  chadburn:\n    image: premoweb/chadburn:latest\n    depends_on:\n      - nginx\n    command: daemon\n    volumes:\n      - /var/run/docker.sock:/var/run/docker.sock:ro\n\n  nginx:\n    image: nginx\n    labels:\n      chadburn.enabled: \"true\"\n      chadburn.job-exec.datecron.schedule: \"@every 5s\"\n      chadburn.job-exec.datecron.command: \"uname -a\"\n```\n\n#### Dynamic Docker Configuration\n\nChadburn can be run in its own container or directly on the host. It will automatically detect any containers that start, stop, or change, utilizing the labeled containers for dynamic task management.\n\n#### Hybrid Configuration (INI + Docker)\n\nYou can combine INI files and Docker labels to manage configurations. Use INI files for global settings or tasks that cannot be defined solely through labels, while Docker labels can be employed for dynamically managed tasks.\n\n```ini\n[global]\nslack-webhook = https://myhook.com/auth\n\n[job-run \"job-executed-on-new-container\"]\nschedule = @hourly\nimage = ubuntu:latest\ncommand = touch /tmp/example\n```\n\nUse Docker labels for dynamic jobs:\n\n```bash\ndocker run -it --rm \\\n    --label chadburn.enabled=true \\\n    --label chadburn.job-exec.test-exec-job.schedule=\"@every 5s\" \\\n    --label chadburn.job-exec.test-exec-job.command=\"uname -a\" \\\n    nginx\n```\n\n#### Running Containers with Labels\n\nYou can add `job-run` labels directly to containers you want to start periodically. Chadburn will automatically detect these containers and schedule them to start according to the specified schedule:\n\n```bash\ndocker run -d --name my-periodic-container \\\n    --label chadburn.job-run.schedule=\"@daily\" \\\n    my-image\n```\n\nThis will create a job that starts the `my-periodic-container` container once a day. The container will be started using the same configuration it was created with.\n\n\u003e **Important Note about job-run with Docker Compose**: When using `job-run` with Docker Compose, there's a key difference from `job-exec`. The `job-run` type is designed to **start new containers** or **start existing stopped containers**, not to execute commands in already running containers. \n\u003e\n\u003e For example, this configuration will **NOT** run the command every 5 seconds inside the running container:\n\u003e ```yaml\n\u003e services:\n\u003e   alpine:\n\u003e     image: alpine\n\u003e     labels:\n\u003e       chadburn.enabled: \"true\"\n\u003e       chadburn.job-run.datecron.schedule: \"@every 5s\"\n\u003e       chadburn.job-run.datecron.command: \"uname -a\"\n\u003e ```\n\u003e\n\u003e Instead, if you want to run a command periodically inside a running container, use `job-exec`:\n\u003e ```yaml\n\u003e services:\n\u003e   alpine:\n\u003e     image: alpine\n\u003e     labels:\n\u003e       chadburn.enabled: \"true\"\n\u003e       chadburn.job-exec.datecron.schedule: \"@every 5s\"\n\u003e       chadburn.job-exec.datecron.command: \"uname -a\"\n\u003e ```\n\n### Logging\n\nChadburn offers three logging drivers that can be configured in the `[global]` section:\n\n- `mail` to send notifications via email.\n- `save` to save structured execution reports in a specified directory.\n- `slack` to send messages through a Slack webhook.\n\nAll logs include timestamps in the format `YYYY-MM-DD HH:MM:SS.mmm`. You can also use Docker's built-in timestamp feature with `docker logs --timestamps chadburn` if you prefer Docker's timestamp format.\n\n#### Logging Options\n\n- `smtp-host`, `smtp-port`, `smtp-user`, `smtp-password`: SMTP server configuration for email notifications.\n- `email-to`, `email-from`: Email addresses for notifications.\n- `mail-only-on-error`: If set to true, emails are only sent when a job fails.\n- `insecure-skip-verify`: If set to true, skips TLS certificate verification for SMTP.\n- `slack-webhook`: Webhook URL for Slack notifications.\n- `slack-only-on-error`: If set to true, Slack messages are only sent when a job fails.\n- `save-folder`: Directory where execution logs should be saved.\n- `save-only-on-error`: If set to true, logs are only saved when a job fails.\n\nExample configuration with logging:\n\n```ini\n[global]\nsmtp-host = smtp.example.com\nsmtp-port = 587\nsmtp-user = user\nsmtp-password = password\nemail-to = alerts@example.com\nemail-from = chadburn@example.com\nmail-only-on-error = true\n\nslack-webhook = https://hooks.slack.com/services/XXX/YYY/ZZZ\nslack-only-on-error = true\n\nsave-folder = /var/log/chadburn\nsave-only-on-error = false\n```\n\n### Metrics (Experimental)\n\nChadburn includes experimental support for Prometheus metrics, allowing you to monitor job executions and performance. When enabled, Chadburn exposes a metrics endpoint that can be scraped by Prometheus.\n\nTo enable metrics, add the `--metrics` flag and specify a listen address:\n\n```bash\nchadburn daemon --config=/etc/chadburn.conf --metrics --listen-address=:8080\n```\n\nAvailable metrics include:\n- Job counts\n- Job execution totals\n- Error counts\n- Execution durations\n\nA preconfigured setup with Prometheus and Grafana is included for easy visualization of metrics. Testing and verification tools are available in the `metrics-tools/` directory. For more information, see:\n- The [metrics documentation](https://chadburn.dev/metrics) for comprehensive information about Chadburn's metrics capabilities\n\n\u003e **Note**: The metrics functionality is currently experimental and may change in future releases.\n\n## Installation\n\nThe simplest way to deploy **Chadburn** is using Docker, as outlined above.\n\nIf you prefer not to use the provided Docker image, you can download a pre-built binary from the [releases page](https://github.com/PremoWeb/chadburn/releases). Chadburn provides binaries for multiple platforms:\n\n- **Linux**: amd64, arm64, and armv7\n- **macOS**: amd64 and arm64 (Apple Silicon)\n- **Windows**: amd64 and arm64\n\nEach release includes SHA256 checksums for verifying the integrity of the downloaded binaries.\n\n### Installing from Binary\n\n1. Download the appropriate binary for your platform from the [releases page](https://github.com/PremoWeb/chadburn/releases).\n2. Extract the archive:\n   ```bash\n   # For Linux/macOS\n   tar -xzf chadburn-\u003cplatform\u003e-\u003carch\u003e.tar.gz\n   \n   # For Windows\n   # Extract the .zip file using your preferred tool\n   ```\n3. Move the binary to a location in your PATH:\n   ```bash\n   # For Linux/macOS\n   sudo mv chadburn-\u003cplatform\u003e-\u003carch\u003e /usr/local/bin/chadburn\n   chmod +x /usr/local/bin/chadburn\n   \n   # For Windows\n   # Move the .exe file to a suitable location and add it to your PATH\n   ```\n\n### Building from Source\n\nIf you prefer to build from source, you'll need Go 1.19 or later:\n\n```bash\ngit clone https://github.com/PremoWeb/chadburn.git\ncd chadburn\ngo build -o chadburn\n```\n\n## Contributing\n\nContributions are welcome! Please feel free to submit a Pull Request.\n\nFor contribution guidelines, development setup, and best practices, visit our [contribution page](https://chadburn.dev/contributing) on our website.\n\n## License\n\nThis project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.\n\n## Acknowledgments\n\n- [Ofelia](https://github.com/mcuadros/ofelia) - The original project that inspired Chadburn.\n- [Cron](https://github.com/robfig/cron) - The Go cron library used by Chadburn.\n- [Docker](https://www.docker.com/) - The container platform that Chadburn integrates with.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fpremoweb%2Fchadburn","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fpremoweb%2Fchadburn","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fpremoweb%2Fchadburn/lists"}