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.

Build Status

Preview

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:

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