Ruby HTML Other
Clone or download
Fetching latest commit…
Cannot retrieve the latest commit at this time.

Zhong Build Status Code Climate Test Coverage Gem Version

Useful, reliable distributed cron. Tired of your cron-like scheduler running key jobs twice? Would you like to be able to run your cron server on multiple machines and have it "just work"? Have we got the gem for you.

Zhong uses Redis to acquire exclusive locks on jobs, as well as recording when they last ran. This means that you can rest easy at night, knowing that your customers are getting their monthly Goat Fancy magazine subscriptions and you are rolling around in your piles of money without a care in the world.

🍊 Battle-tested at Instacart


Add this line to your application’s Gemfile:

gem 'zhong'


Zhong schedule

Create a definition file, let's call it zhong.rb:

Zhong.redis = ENV["ZHONG_REDIS_URL"])

Zhong.schedule do
  category "stuff" do
    every 5.seconds, "foo" do
      puts "foo"

    every(1.minute, "running biz at 26th and 27th minute", at: ["**:26", "**:27"]) { puts "biz" }
    every(1.week, "running baz on mon and wed", at: ["mon 22:45", "wed 23:13"]) { puts "baz" }
    every(10.seconds, "boom every 10 seconds") { raise "fail" }

  category "clutter" do
    every(1.second, "compute", if: -> (t) { t.wday == 3 && rand < 0.5 }) do
      puts "something happened on wednesday, maybe"

  # note: callbacks that explicitly false will cause event to not run
  on(:before_tick) do
    puts "ding"

  on(:after_tick) do
    puts "dong"

  on(:before_run) do |job, time|
    puts "running #{job}"
    true # can conditionally run a specific job

  on(:after_run) do |job, time, ran|
    puts "#{job} ran?: #{ran}"

  on(:before_disable) do |job|
    puts "#{job} is going to be disabled"

  on(:after_disable) do |job|
    puts "#{job} disabled"

  on(:before_enable) do |job|
    puts "#{job} is going to be enabled"

  on(:after_enable) do |job|
    puts "#{job} enabled"

  error_handler do |e, job|
    puts "dang, #{job} messed up: #{e}"

This file only describes what should be the schedule. Nothing will be executed until we actually run


after describing the Zhong schedule.

Zhong cron process

You can run the cron process that will execute your code from the definitions in the zhong.rb file by running:

zhong zhong.rb

Web UI

Zhong comes with a web application that can display jobs, their last run and enable/disable them.

This is a Sinatra application that requires at least v2.0.0. You can add to your Gemfile

gem 'sinatra', "~>2.0"

It can be protected by HTTP basic authentication by setting the following environment variables:

  • ZHONG_WEB_USERNAME: the username
  • ZHONG_WEB_PASSWORD: the password

You'll need to load the Zhong schedule to be able to see jobs in the web UI, typically by requiring your zhong.rb definition file.


Load the Zhong schedule by creating an initializer at config/initializers/zhong.rb, with the following content:

require "#{Rails.root}/zhong.rb"

Add the following to your config/routes.rb:

require 'zhong/web'

Rails.application.routes.draw do
  # Other routes here...

  mount Zhong::Web, at: "/zhong"


View the changelog.


Everyone is encouraged to help improve this project. Here are a few ways you can help: