Clockwork Web Plus

A fully compatible drop-in enhancement to ankane/clockwork_web, providing a modern web interface for Clockwork with fuzzy search, manual job run, overdue visibility, and hourly health checks.

Preview

Screen.Recording.2025-11-11.at.21.39.26.mov

Features

Core (from `clockwork_web`)

see list of jobs
monitor jobs ( when they were last run at)
Temporarily disable jobs

New compared to clockwork_web

fuzzy find search across jobs
run any job immediately through the Run now button
view the Ruby implementation of each job
highlight overdue jobs at a glance
optional hourly health check callback with custom alerting

Installation

Add this line to your application’s Gemfile:

gem "clockwork_web_plus"

Tip

Already using clockwork_web? Keep your existing ClockworkWeb::Engine mount and initializers—no renaming needed. ClockworkWebPlus aliases ClockworkWeb, so it works out of the box.

And add it to your config/routes.rb.

mount ClockworkWebPlus::Engine, at: "clockwork"

Important

Secure the dashboard in production. Protect access with Basic Auth, Devise, or your app’s auth layer to avoid exposing job controls and status.

To monitor and disable jobs, hook up Redis in an initializer.

ClockworkWebPlus.redis = Redis.new

Basic Authentication

Set the following variables in your environment or an initializer.

ENV["CLOCKWORK_USERNAME"] = "chaadow"
ENV["CLOCKWORK_PASSWORD"] = "secret"

Note

These are example credentials. Use environment-specific secrets and rotate them regularly.

Devise

authenticate :user, ->(user) { user.admin? } do
  mount ClockworkWebPlus::Engine, at: "clockwork"
end

Tip

Any authentication framework works—wrap the mount with whatever guard your app already uses for admin/ops access.

Monitoring

ClockworkWebPlus.running?
ClockworkWebPlus.multiple?

Note

running? reflects recent heartbeats. multiple? indicates multiple active Clockwork processes (based on heartbeat contention).

Customize

Change clock path

ClockworkWebPlus.clock_path = Rails.root.join("clock") # default

Note

The default clock_path matches clockwork_web. Change it only if your clock file lives elsewhere.

Turn off monitoring

ClockworkWebPlus.monitor = false

Caution

Disabling monitoring stops heartbeats and multiple-process detection. The dashboard won’t show “running” status, but other features still work.

Overdue Jobs & Health Checks

The dashboard highlights overdue jobs based on schedule and last run. You can also configure an hourly health check to alert when jobs are overdue:

ClockworkWebPlus.on_health_check = ->(overdue_jobs:) do
  # backlog contains array of hashes with details like:
  # { job:, should_have_run_at:, last_run:, period:, at: { hour:, min: } }
  if overdue_jobs.any?
    # send notification to Slack, email, etc.
  end
end

Note

Overdue detection uses ClockworkWebPlus.warning_threshold (default: 300 seconds).

For @at schedules: a job is overdue when the most recent scheduled time has passed by more than warning_threshold and the job hasn’t run since that time.
For periodic jobs (no @at): a job is overdue when now > last_run + period + warning_threshold.

Example:

# consider jobs overdue 10 minutes after their expected time
ClockworkWebPlus.warning_threshold = 600

Important

With Redis configured, the health check runs at most once per hour across processes. Without Redis, throttling is per-process and approximate.

History

View the changelog

Compatibility

This gem is a drop-in replacement for clockwork_web. For backward compatibility, the original namespace is aliased:

# Both of these work:
mount ClockworkWebPlus::Engine, at: "clockwork"
mount ClockworkWeb::Engine, at: "clockwork"

Tip

Adopting this gem can be as simple as swapping the gem name in your Gemfile. Your existing ClockworkWeb mounts and initializers continue to work unchanged.

Contributing

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

Report bugs
Fix bugs and submit pull requests
Write, clarify, or fix documentation
Suggest or add new features

To get started with development:

git clone https://github.com/chaadow/clockwork_web_plus.git
cd clockwork_web_plus
bundle install
bundle exec rake test