{"id":13425040,"url":"https://github.com/ajvb/kala","last_synced_at":"2025-05-14T04:07:32.838Z","repository":{"id":28974211,"uuid":"32500617","full_name":"ajvb/kala","owner":"ajvb","description":"Modern Job Scheduler","archived":false,"fork":false,"pushed_at":"2024-02-19T04:00:12.000Z","size":4428,"stargazers_count":2146,"open_issues_count":14,"forks_count":188,"subscribers_count":62,"default_branch":"master","last_synced_at":"2025-04-10T22:35:00.250Z","etag":null,"topics":["go","golang","golang-application","iso8601","scheduler","service"],"latest_commit_sha":null,"homepage":"","language":"Go","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/ajvb.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2015-03-19T04:24:19.000Z","updated_at":"2025-04-08T16:58:03.000Z","dependencies_parsed_at":"2024-06-18T12:35:17.937Z","dependency_job_id":"c8588739-2ad3-4cf4-93a6-7f8dcc43c827","html_url":"https://github.com/ajvb/kala","commit_stats":{"total_commits":456,"total_committers":43,"mean_commits":"10.604651162790697","dds":0.5679824561403508,"last_synced_commit":"4eb4f7ae04346e0f6ba92d0c63a619ca9c59559c"},"previous_names":[],"tags_count":17,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ajvb%2Fkala","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ajvb%2Fkala/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ajvb%2Fkala/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ajvb%2Fkala/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/ajvb","download_url":"https://codeload.github.com/ajvb/kala/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":254069209,"owners_count":22009507,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["go","golang","golang-application","iso8601","scheduler","service"],"created_at":"2024-07-31T00:01:02.999Z","updated_at":"2025-05-14T04:07:32.798Z","avatar_url":"https://github.com/ajvb.png","language":"Go","readme":"# Kala\n\n[![GoDoc](https://godoc.org/github.com/ajvb/kala?status.svg)](https://godoc.org/github.com/ajvb/kala)\n![golangci-lint](https://github.com/ajvb/kala/workflows/golangci-lint/badge.svg)\n[![Circle CI](https://circleci.com/gh/ajvb/kala.svg?style=svg)](https://circleci.com/gh/ajvb/kala)\n[![Coverage Status](https://coveralls.io/repos/ajvb/kala/badge.svg?branch=master\u0026service=github)](https://coveralls.io/github/ajvb/kala?branch=master)\n\n![Dashboard](assets/job-list.png)\n\nKala is a simplistic, modern, and performant job scheduler written in Go.  Features:\n\n- Single binary\n- No dependencies\n- JSON over HTTP API\n- Job Stats\n- Configurable Retries\n- Scheduling with ISO 8601 Date and Interval notation\n- Dependent Jobs\n- Persistent with several database drivers\n- Web UI\n\n**Note that it is not battle-tested. Use at your own risk.**\n\nKala was inspired by the desire for a simpler [Chronos](https://github.com/airbnb/chronos) (developed by Airbnb). Kala is Chronos for the rest of us.\n\nIf you need fault tolerance, distributed features, massive scale, then I recommend checking out [Chronos](https://github.com/airbnb/chronos). This is designed to be the Chronos for start-ups.\n\n## Installing Kala\n\n*Kala uses Go Modules*\n\n1. Get Kala\n\n\t```\n\tgo get github.com/ajvb/kala\n\t```\n\n2. Run Kala\n\n\t```\n\tkala serve\n\t```\n\n# Getting Started\n\nOnce you have installed Kala onto the machine you would like to use, you can follow the below steps to start using it.\n\nTo run Kala as a server:\n\n```console\n$ kala serve\nINFO[0000] Preparing cache\nINFO[0000] Starting server on port :8000\n\n$ kala serve -p 2222\nINFO[0000] Preparing cache\nINFO[0000] Starting server on port :2222\n```\n\nKala uses BoltDB by default for the job database by using `jobdb` and `boltpath` params:\n\n```bash\nkala serve --jobdb=boltdb --boltpath=/path/to/dir\n```\n\nuse Redis by using the `jobdb`, `jobdb-address` and `jobdb-password` params:\n\n```bash\nkala serve --jobdb=redis --jobdb-address=127.0.0.1:6379 --jobdb-password=password\n```\n\nuse Consul by using the `jobdb` and `jobdb-address` params:\n\n```bash\nkala serve --jobdb=consul --jobdb-address=127.0.0.1:8500\n```\n\nuse Mongo by using the `jobdb`, `jobdb-address`, `jobdb-username`, and `jobdb-password` params:\n\n```bash\nkala serve --jobdb=mongo --jobdb-address=server1.example.com,server2.example.com --jobdb-username=admin --jobdb-password=password\n```\n\nuse Postgres by using the `jobdb`, `jobdb-address` params:\n\n```bash\nkala serve --jobdb=postgres --jobdb-address=server1.example.com/kala --jobdb-username=admin --jobdb-password=password\n```\n\nuse MariaDB, MySQL by using the `jobdb`, `jobdb-address`, `jobdb-tls-capath`, `jobdb-tls-certpath`, `jobdb-tls-keypath`, `jobdb-tls-servername` params:\n\n```bash\nkala serve --jobdb=mariadb --jobdb-address=(server1.example.com)/kala --jobdb-username=admin --jobdb-password=password\n\nkala serve --jobdb=mysql --jobdb-address=\"tcp(server1.example.com:3306)/kala?tls=custom\" --jobdb-username=admin --jobdb-password=password --jobdb-tls-capath=/path/to/server-ca.pem --jobdb-tls-certpath=/path/to/client-cert.pem --jobdb-tls-keypath=/path/to/client-key.pem --jobdb-tls-servername=server1.example.com\n```\n\nKala runs on `127.0.0.1:8000` by default. You can easily test it out by curling the metrics path.\n\n```bash\n$ curl http://127.0.0.1:8000/api/v1/stats/\n{\"Stats\":{\"ActiveJobs\":2,\"DisabledJobs\":0,\"Jobs\":2,\"ErrorCount\":0,\"SuccessCount\":0,\"NextRunAt\":\"2015-06-04T19:25:16.82873873-07:00\",\"LastAttemptedRun\":\"0001-01-01T00:00:00Z\",\"CreatedAt\":\"2015-06-03T19:58:21.433668791-07:00\"}}\n```\n\nOnce it's up in running, you can utilize curl or the official go client to interact with Kala. Also check out the examples directory.\n\n### Examples of Usage\n\nThere are more examples in the [examples directory](https://github.com/ajvb/kala/tree/master/examples) within this repo. Currently its pretty messy. Feel free to submit a new example if you have one.\n\n# Deployment\n\n### Supervisord\n\nAfter installing supervisord, open its config file (`/etc/supervisor/supervisord.conf` is the default usually) and add something like:\n\n```\n[program:kala]\ncommand=kala serve\nautorestart=true\nstdout_logfile=/var/log/kala.stdout.log\nstderr_logfile=/var/log/kala.stderr.log\n```\n\n### Docker\n\nIf you have docker installed, you can build the dockerfile in this directory with\n```docker build -t kala .```\nand run it as a daemon with:\n```docker run -it -d -p 8000:8000 kala```\n\n# API v1 Docs\n\nAll routes have a prefix of `/api/v1`\n\n## Client Libraries\n\n#### Official:\n* [Go](https://github.com/ajvb/kala/tree/master/client) - Docs: http://godoc.org/github.com/ajvb/kala/client\n    ```bash\n    go get github.com/ajvb/kala/client\n    ```\n\n#### Contrib:\n* [Node.js](https://www.npmjs.com/package/kala-node)\n  ```shell\n  npm install kala-node\n  ```\n\n* [Python](https://github.com/dmajere/kala-python)\n  ```shell\n  pip install git+https://github.com/dmajere/kala-python.git\n  ```\n\n## Job Data Struct\n\n[Docs can be found here](http://godoc.org/github.com/ajvb/kala/job#Job)\n\n## Things to Note\n\n* If schedule is omitted, the job will run immediately.\n\n\n## Job JSON Example\n\n```\n{\n        \"name\":\"test_job\",\n        \"id\":\"93b65499-b211-49ce-57e0-19e735cc5abd\",\n        \"command\":\"bash /home/ajvb/gocode/src/github.com/ajvb/kala/examples/example-kala-commands/example-command.sh\",\n        \"owner\":\"\",\n        \"disabled\":false,\n        \"dependent_jobs\":null,\n        \"parent_jobs\":null,\n        \"schedule\":\"R2/2015-06-04T19:25:16.828696-07:00/PT10S\",\n        \"retries\":0,\n        \"epsilon\":\"PT5S\",\n        \"success_count\":0,\n        \"last_success\":\"0001-01-01T00:00:00Z\",\n        \"error_count\":0,\n        \"last_error\":\"0001-01-01T00:00:00Z\",\n        \"last_attempted_run\":\"0001-01-01T00:00:00Z\",\n        \"next_run_at\":\"2015-06-04T19:25:16.828794572-07:00\"\n}\n```\n\n## Breakdown of schedule string. (ISO 8601 Notation)\n\nExample `schedule` string:\n\n```\nR2/2017-06-04T19:25:16.828696-07:00/PT10S\n```\n\nThis string can be split into three parts:\n\n```\nNumber of times to repeat/Start Datetime/Interval Between Runs\n```\n\n#### Number of times to repeat\n\nThis is designated with a number, prefixed with an `R`. Leave out the number if it should repeat forever.\n\nExamples:\n\n* `R` - Will repeat forever\n* `R1` - Will repeat once\n* `R231` - Will repeat 231 times.\n\n#### Start Datetime\n\nThis is the datetime for the first time the job should run.\n\nKala will return an error if the start datetime has already passed.\n\nExamples:\n\n* `2017-06-04T19:25:16`\n* `2017-06-04T19:25:16.828696`\n* `2017-06-04T19:25:16.828696-07:00`\n* `2017-06-04T19:25:16-07:00`\n\n*To Note: It is recommended to include a timezone within your schedule parameter.*\n\n#### Interval Between Runs\n\nThis is defined by the [ISO8601 Interval Notation](https://en.wikipedia.org/wiki/ISO_8601#Time_intervals).\n\nIt starts with a `P`, then you can specify years, months, or days, then a `T`, preceded by hours, minutes, and seconds.\n\nLets break down a long interval: `P1Y2M10DT2H30M15S`\n\n* `P` - Starts the notation\n* `1Y` - One year\n* `2M` - Two months\n* `10D` - Ten days\n* `T` - Starts the time second\n* `2H` - Two hours\n* `30M` - Thirty minutes\n* `15S` - Fifteen seconds\n\nNow, there is one alternative. You can optionally use just weeks. When you use the week operator, you only get that. An example of using the week operator for an interval of every two weeks is `P2W`.\n\nExamples:\n\n* `P1DT1M` - Interval of one day and one minute\n* `P1W` - Interval of one week\n* `PT1H` - Interval of one hour.\n\n### More Information on ISO8601\n\n* [Wikipedia's Article](https://en.wikipedia.org/wiki/ISO_8601)\n\n## Overview of routes\n\n| Task | Method | Route |\n| --- | --- | --- |\n|Creating a Job | POST | /api/v1/job/ |\n|Getting a list of all Jobs | GET | /api/v1/job/ |\n|Getting a Job | GET | /api/v1/job/{id}/ |\n|Deleting a Job | DELETE | /api/v1/job/{id}/ |\n|Deleting all Jobs | DELETE | /api/v1/job/all/ |\n|Getting metrics about a certain Job | GET | /api/v1/job/stats/{id}/ |\n|Starting a Job manually | POST | /api/v1/job/start/{id}/ |\n|Disabling a Job | POST | /api/v1/job/disable/{id}/ |\n|Enabling a Job | POST | /api/v1/job/enable/{id}/ |\n|Getting app-level metrics | GET | /api/v1/stats/ |\n\n\n## /job\n\nThis route accepts both a GET and a POST. Performing a GET request will return a list of all currently running jobs.\nPerforming a POST (with the correct JSON) will create a new Job.\n\nNote: When creating a Job, the only fields that are required are the `Name` and the `Command` field. But, if you omit the `Schedule` field, the job will be ran immediately.\n\nExample:\n```bash\n$ curl http://127.0.0.1:8000/api/v1/job/\n{\"jobs\":{}}\n$ curl http://127.0.0.1:8000/api/v1/job/ -d '{\"epsilon\": \"PT5S\", \"command\": \"bash /home/ajvb/gocode/src/github.com/ajvb/kala/examples/example-kala-commands/example-command.sh\", \"name\": \"test_job\", \"schedule\": \"R2/2017-06-04T19:25:16.828696-07:00/PT10S\"}'\n{\"id\":\"93b65499-b211-49ce-57e0-19e735cc5abd\"}\n$ curl http://127.0.0.1:8000/api/v1/job/\n{\n    \"jobs\":{\n        \"93b65499-b211-49ce-57e0-19e735cc5abd\":{\n            \"name\":\"test_job\",\n            \"id\":\"93b65499-b211-49ce-57e0-19e735cc5abd\",\n            \"command\":\"bash /home/ajvb/gocode/src/github.com/ajvb/kala/examples/example-kala-commands/example-command.sh\",\n            \"owner\":\"\",\n            \"disabled\":false,\n            \"dependent_jobs\":null,\n            \"parent_jobs\":null,\n            \"schedule\":\"R2/2017-06-04T19:25:16.828696-07:00/PT10S\",\n            \"retries\":0,\n            \"epsilon\":\"PT5S\",\n            \"success_count\":0,\n            \"last_success\":\"0001-01-01T00:00:00Z\",\n            \"error_count\":0,\n            \"last_error\":\"0001-01-01T00:00:00Z\",\n            \"last_attempted_run\":\"0001-01-01T00:00:00Z\",\n            \"next_run_at\":\"2017-06-04T19:25:16.828794572-07:00\"\n        }\n    }\n}\n```\n\n## /job/{id}\n\nThis route accepts both a GET and a DELETE, and is based off of the id of the Job. Performing a GET request will return a full JSON object describing the Job.\nPerforming a DELETE will delete the Job.\n\nExample:\n```bash\n$ curl http://127.0.0.1:8000/api/v1/job/93b65499-b211-49ce-57e0-19e735cc5abd/\n{\"job\":{\"name\":\"test_job\",\"id\":\"93b65499-b211-49ce-57e0-19e735cc5abd\",\"command\":\"bash /home/ajvb/gocode/src/github.com/ajvb/kala/examples/example-kala-commands/example-command.sh\",\"owner\":\"\",\"disabled\":false,\"dependent_jobs\":null,\"parent_jobs\":null,\"schedule\":\"R2/2017-06-04T19:25:16.828696-07:00/PT10S\",\"retries\":0,\"epsilon\":\"PT5S\",\"success_count\":0,\"last_success\":\"0001-01-01T00:00:00Z\",\"error_count\":0,\"last_error\":\"0001-01-01T00:00:00Z\",\"last_attempted_run\":\"0001-01-01T00:00:00Z\",\"next_run_at\":\"2017-06-04T19:25:16.828737931-07:00\"}}\n$ curl http://127.0.0.1:8000/api/v1/job/93b65499-b211-49ce-57e0-19e735cc5abd/ -X DELETE\n$ curl http://127.0.0.1:8000/api/v1/job/93b65499-b211-49ce-57e0-19e735cc5abd/\n```\n\n## /job/stats/{id}\n\nExample:\n```bash\n$ curl http://127.0.0.1:8000/api/v1/job/stats/5d5be920-c716-4c99-60e1-055cad95b40f/\n{\"job_stats\":[{\"JobId\":\"5d5be920-c716-4c99-60e1-055cad95b40f\",\"RanAt\":\"2017-06-03T20:01:53.232919459-07:00\",\"NumberOfRetries\":0,\"Success\":true,\"ExecutionDuration\":4529133}]}\n```\n\n## /job/start/{id}\n\nExample:\n```bash\n$ curl http://127.0.0.1:8000/api/v1/job/start/5d5be920-c716-4c99-60e1-055cad95b40f/ -X POST\n```\n\n## /job/disable/{id}\n\nExample:\n```bash\n$ curl http://127.0.0.1:8000/api/v1/job/disable/5d5be920-c716-4c99-60e1-055cad95b40f/ -X POST\n```\n\n## /job/enable/{id}\n\nExample:\n```bash\n$ curl http://127.0.0.1:8000/api/v1/job/enable/5d5be920-c716-4c99-60e1-055cad95b40f/ -X POST\n```\n\n## /stats\n\nExample:\n```bash\n$ curl http://127.0.0.1:8000/api/v1/stats/\n{\"Stats\":{\"ActiveJobs\":2,\"DisabledJobs\":0,\"Jobs\":2,\"ErrorCount\":0,\"SuccessCount\":0,\"NextRunAt\":\"2017-06-04T19:25:16.82873873-07:00\",\"LastAttemptedRun\":\"0001-01-01T00:00:00Z\",\"CreatedAt\":\"2017-06-03T19:58:21.433668791-07:00\"}}\n```\n\n## Debugging Jobs\n\nThere is a command within Kala called `run` which will immediately run a command as Kala would run it live, and then gives you a response on whether it was successful or not. Allows for easier and quicker debugging of commands.\n\n```bash\n$ kala run \"ruby /home/user/ruby/my_ruby_script.rb\"\nCommand Succeeded!\n$ kala run \"ruby /home/user/other_dir/broken_script.rb\"\nFATA[0000] Command Failed with err: exit status 1\n```\n\n## Dependent Jobs\n\n### How to add a dependent job\n\nCheck out this [example for how to add dependent jobs](https://github.com/ajvb/kala/blob/master/examples/python/example_dependent_jobs.py) within a python script.\n\n### Notes on Dependent Jobs\n\n* Dependent jobs follow a rule of First In First Out\n* A child will always have to wait until a parent job finishes before it runs\n* A child will not run if its parent job does not.\n* If a child job is disabled, it's parent job will still run, but it will not.\n* If a child job is deleted, it's parent job will continue to stay around.\n* If a parent job is deleted, unless its child jobs have another parent, they will be deleted as well.\n\n# Original Contributors and Contact\n\nOriginal Author and Core Maintainer:\n\n* AJ Bahnken / [@ajvbahnken](http://twitter.com/ajvbahnken) / aj@ajvb.me\n\nOriginal Reviewers:\n\n* Sam Dolan / [@samdolan](https://github.com/samdolan/)\n* Steve Phillips / [@elimisteve](http://twitter.com/elimisteve)\n\n#### Donate\n\n[![Flattr this git repo](http://api.flattr.com/button/flattr-badge-large.png)](https://flattr.com/submit/auto?user_id=ajvb\u0026url=https://github.com/ajvb/kala\u0026title=Kala\u0026language=\u0026tags=github\u0026category=software)\n","funding_links":[],"categories":["Go","Software Packages","软件包","DevOps Tools","軟件包","Go Tools","Go 工具","Repositories"],"sub_categories":["DevOps Tools","DevOps 工具","Contents","DevOps工具","代码分析","devops 工具"],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fajvb%2Fkala","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fajvb%2Fkala","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fajvb%2Fkala/lists"}