Dkron: a distributed cron scheduler built on Raft and Serf

The problem Dkron solves: cron that survives a dead node

A crontab lives on one machine. When that machine is rebooting, out of disk, or simply gone, the jobs on it do not run, and nothing tells you. Dkron's README frames the project as a distributed cron service for cloud native environments, and the stated focus is reliability across a cluster rather than features on a single host. The intended user is someone who already operates more than one server and treats scheduled work as production traffic: batch exports, report generation, cache warming, cleanup tasks that must happen whether or not a particular instance is healthy.

The README claims no single point of failure, attributing that to the Gossip protocol and fault tolerant distributed databases. It also cites two design influences: the Google paper Reliable Cron across the Planet and Airbnb Chronos. Both point at the same idea, that a scheduler should be a replicated service with a leader, not a process bound to one machine's clock. The project ships a dashboard, and the README lists client libraries in Python, Ruby and PHP, a Terraform provider, a Chef cookbook and a Django integration, so the expectation is that jobs are created and inspected programmatically, not by editing files on a server.

How the cluster actually works: Raft for state, Serf for membership

The dependency list in go.mod is the clearest description of the architecture. hashicorp/raft and hashicorp/raft-boltdb provide the replicated log and its on-disk store, hashicorp/serf and hashicorp/memberlist provide gossip-based membership and failure detection, and hashicorp/go-discover handles finding peers. Job definitions and scheduling state live in the Raft-replicated store, so every server node agrees on what should run and when. Serf propagates membership, which is how nodes learn about each other and how a lost node is noticed. The README describes this combination as the source of fault tolerance, reliability and scalability.

A node runs as either a server or an agent. Servers participate in consensus and hold the scheduler; agents join the cluster and execute work. The docker-compose.yml in the repository shows the split directly: one service starts with agent --server --bootstrap-expect=1, a second uses --retry-join=dkron:8946 with --bootstrap-expect=3, and a third runs as a plain agent with --retry-join and a --tag agent=true. Port 8946 is the Serf traffic, 6868 appears alongside it for server communication, and 8080 serves the API and UI. Scheduling itself is delegated to robfig/cron/v3, so the expression syntax is the familiar five-field cron format rather than something invented for the project.

That design has a cost the README does not dwell on. Raft requires a quorum, so the number of server nodes matters: --bootstrap-expect=3 in the compose file is not decoration, it is the number of servers the cluster expects before it forms. A two-server deployment is worse than either one or three, because losing one node leaves no majority. Agents do not have that constraint, which is why the README's scaling example adds ten agents against four servers.

Installing Dkron with Docker Compose and adding a first job

The README points to dkron.io/docs/basics/installation for full instructions and calls Docker with Docker Compose the best way to test and develop. The repository's docker-compose.yml defines a single leader node, a three-server group and an agent pool, so the quickstart is one command from the repository root.

docker compose up -d

The README states the UI should then be available at http://localhost:8080/ui. That first service maps 8080 to the host, so the dashboard and the HTTP API are reachable from your browser, while 8946 and 6868 are exposed for cluster traffic.

Scaling out uses the same compose file. The README gives these two commands, which add three more server nodes and nine more agents on top of the ones already defined.

docker compose up -d --scale dkron-server=4
docker compose up -d --scale dkron-agent=10

Job creation is not shown in the README. It says to read the API docs at dkron.io/api/ to add jobs to the system, and the UI at /ui is the other route. That is a real gap in the quickstart: you can bring the cluster up in a minute, but the README does not walk you through defining a job, so budget time for the API reference before you can call the setup finished.

For development against local changes, the README gives a separate compose file. It also documents Mailpit for email notification testing, either as part of that stack or standalone.

docker compose -f docker-compose.dev.yml up

docker run -p 8025:8025 -p 1025:1025 axllent/mailpit

Captured messages appear at http://localhost:8025. The README also mentions ./scripts/test-ci-locally.sh, which starts Mailpit and runs the test suite with the same configuration as GitHub Actions.

Where Dkron is the wrong tool

If you have one server and five jobs, Dkron asks you to run a consensus cluster to schedule work that cron already handles. You would be operating Raft, Serf and a persistent log store to gain fault tolerance you cannot use, because there is no second machine to fail over to. The README's own framing, thousands of nodes and high volumes of scheduled jobs, describes the scale where the overhead pays off.

The second limitation is documentation depth in the quickstart path. The README covers deployment, development, email testing and CI, and then hands job creation to the API docs. Anyone evaluating Dkron from the repository alone will not see a worked example of a job definition, a retry policy or a notification target. That is not a defect in the software, but it does mean the README is a deployment guide rather than an onboarding guide.

Third, the licence is not the permissive default. Dkron is LGPL-3.0, and the repository root also contains a COMM-LICENSE file, which suggests commercial terms exist alongside the open source licence. The README does not explain the relationship between the two, so if you plan to embed Dkron in a product, that is a question for your own legal review rather than something the documentation answers.

Finally, the README does not document rollback, downgrade or upgrade procedures between versions. Releases are frequent (v4.2.0, v4.1.3 and v4.1.2 all landed within about two months), so a version pin is the practical mitigation, but nothing in the repository describes what happens to Raft state when you move between them.

Dkron compared with Cronicle and with plain cron

Cronicle is the closest thing to a named alternative in the search data, and the two take different routes to the same goal. Cronicle is a self-hosted scheduler with a web interface aimed at replacing crontab on one or a few machines. Dkron's README describes a Go binary built on Raft and Serf, with server and agent roles, and explicitly targets clusters where no single node is a point of failure. The practical difference is what you operate: Cronicle is closer to a single application you install and point at a job list, while Dkron is a distributed system whose behaviour depends on how many server nodes you run and whether they can reach each other on 8946 and 6868.

Plain cron is the other comparison worth making, because it is what most teams actually have. Cron has no cluster state, no API, no UI and no consensus, and it costs nothing to run. Dkron's value appears only when a missed job has a real cost and a single machine is not a safe place to keep the schedule. The README's claim of no single points of failure is the whole argument, and it only holds if you deploy more than one server.

Maintenance, releases and what the licence means for adopters

The repository is not archived and the last push was on 2026-09-22, one day before the most recent release tag, v4.2.0, which is dated 2026-09-20. Two more releases, v4.1.3 and v4.1.2, arrived in the preceding two months. That cadence means upgrades are something you will do repeatedly, not once, and nothing in the repository describes a supported upgrade path, so pinning the image tag rather than relying on dkron/dkron:latest is the safer default. The compose file uses latest, which is convenient for a first look and a poor choice for anything you depend on.

Upgrade cost also depends on the Raft store. Because job state is replicated through hashicorp/raft with a BoltDB backend, the cluster carries persistent state between versions, and the README says nothing about compatibility guarantees across releases. Test an upgrade on a throwaway cluster before touching production.

On licensing: Dkron is LGPL-3.0 and the repository root contains both a LICENSE file and a COMM-LICENSE file. The README does not describe what the commercial licence covers or when it applies. LGPL is a copyleft licence with specific conditions around linking and modification, and those conditions differ from MIT or Apache-2.0 in ways that matter for some distribution models. This article is not legal advice; read LICENSE and COMM-LICENSE directly and have counsel assess your specific use.

Editorial conclusion

Dkron fits teams that already run a cluster and need scheduled commands to survive a single node dying, with a UI and an HTTP API instead of hand-edited crontabs. It is the wrong choice for a single box running a handful of jobs, where plain cron or a systemd timer has no consensus layer to operate. Before adopting it, confirm which of the ports in docker-compose.yml your network allows (8080, 8946, 6868), check whether the LGPL-3.0 terms and the separate COMM-LICENSE file match how you ship software, and read the installation page at dkron.io/docs/basics/installation rather than trusting a compose file alone.

Frequently asked questions

Official sources

1. dkron-io/dkron on GitHub
2. Issues
3. License: LGPL-3.0
4. README
5. Releases