Kaal

Kaal is a distributed cron scheduler for Ruby that safely executes scheduled tasks across multiple nodes.

🧭 Project Structure

This repository contains the Kaal gem and its documentation site.


/repo-root
├── .github/              # CI workflows, issue templates
├── kaal/           # Gem source (lib/, bin/, gemspec)
├── docs/                 # Documentation site (Jekyll + Markdown)
└── README.md             # This file

🧩 What It Does

kaal lets you register, schedule, and safely run recurring tasks across multiple Ruby nodes.
It ensures exactly-once dispatching per cron tick using distributed locks via Redis or PostgreSQL advisory locks.

It’s scheduler-agnostic and works with any background job system (ActiveJob, Sidekiq, Resque, etc.), while exposing a clean Ruby API, CLI, and Rails integration.

📚 Documentation

Comprehensive guides are published at:

👉 https://kaal.codevedas.com

Section	Description
Overview & Motivation	Why Kaal exists
Installation & Setup	Gem setup and initializer
Usage	Registering jobs, CLI, and Rake tasks
FAQ / Troubleshooting	Common issues and fixes

🛠️ Local Development

1. Clone and setup

git clone https://github.com/CodevedasInc/kaal.git
cd kaal
bundle install

2. Run specs

bin/rspec-unit

3. Lint and format

bin/rubocop

4. Reek

bin/Reek

🧪 Running the Gem Locally

You can load a local version of the gem in a test Rails app:

gem build kaal.gemspec
gem install ./kaal-0.1.0.gem

Or reference it directly in another app’s Gemfile:

gem "kaal", path: "../kaal/kaal"

🚀 Docs Site (Jekyll)

The docs/ directory is a Jekyll site used for GitHub Pages.

Run locally

cd docs
bundle install
bundle exec jekyll serve

Then open: 👉 http://localhost:4000

⚙️ Continuous Integration

GitHub Actions workflows include:

Workflow	Purpose
`ci.yml`	Runs tests (RSpec + RuboCop) on all Ruby versions
`release.yml`	Builds and publishes gem to RubyGems
`jekyll-gh-pages.yml`	Builds and deploys docs to GitHub Pages

Contributing, Security, Conduct

Contributing: see CONTRIBUTING.md
Security policy: see SECURITY.md
Code of Conduct: see CODE_OF_CONDUCT.md

kaal

Runtime