{"id":25940508,"url":"https://github.com/lautarojayat/ruok","last_synced_at":"2026-05-11T10:32:38.793Z","repository":{"id":212339605,"uuid":"721614397","full_name":"LautaroJayat/ruok","owner":"LautaroJayat","description":"Scheduler and executor engine for RUOK service health monitor","archived":false,"fork":false,"pushed_at":"2023-12-20T00:39:49.000Z","size":1337,"stargazers_count":2,"open_issues_count":0,"forks_count":1,"subscribers_count":0,"default_branch":"main","last_synced_at":"2025-03-04T05:16:54.775Z","etag":null,"topics":["cronjob","crontab","health","healthcheck","monitoring","opensource","postgres","postgresql"],"latest_commit_sha":null,"homepage":"","language":"Go","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/LautaroJayat.png","metadata":{"files":{"readme":"Readme.md","changelog":null,"contributing":null,"funding":".github/FUNDING.yml","license":"LICENSE.md","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null},"funding":{"patreon":"ru_ok"}},"created_at":"2023-11-21T12:27:09.000Z","updated_at":"2023-12-29T17:11:38.000Z","dependencies_parsed_at":"2023-12-18T22:23:08.373Z","dependency_job_id":"a4c7ceba-ea8a-4f23-bdcc-7253e41e2e06","html_url":"https://github.com/LautaroJayat/ruok","commit_stats":{"total_commits":116,"total_committers":2,"mean_commits":58.0,"dds":"0.12068965517241381","last_synced_commit":"6290bb2333a1f26646b86e2e733380d5d88e9a2f"},"previous_names":["back-end-labs/ruok-scheduler","back-end-labs/ruok","lautarojayat/ruok"],"tags_count":0,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/LautaroJayat%2Fruok","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/LautaroJayat%2Fruok/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/LautaroJayat%2Fruok/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/LautaroJayat%2Fruok/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/LautaroJayat","download_url":"https://codeload.github.com/LautaroJayat/ruok/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":241787484,"owners_count":20020101,"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":["cronjob","crontab","health","healthcheck","monitoring","opensource","postgres","postgresql"],"created_at":"2025-03-04T05:16:57.489Z","updated_at":"2026-05-11T10:32:38.740Z","avatar_url":"https://github.com/LautaroJayat.png","language":"Go","funding_links":["https://patreon.com/ru_ok"],"categories":[],"sub_categories":[],"readme":"# RUOK Scheduler\n\n![Testing](https://github.com/back-end-labs/ruok/actions/workflows/test.yaml/badge.svg?event=push\u0026branch=main)\n[![Go Report Card](https://goreportcard.com/badge/github.com/back-end-labs/ruok)](https://goreportcard.com/report/github.com/helm/helm)\n![Version](https://img.shields.io/badge/version-unstable-blue)\n[![License](https://img.shields.io/github/license/back-end-labs/ruok)](/LICENSE)\n[![FOSSA Status](https://app.fossa.com/api/projects/git%2Bgithub.com%2Fback-end-labs%2Fruok.svg?type=shield\u0026issueType=license)](https://app.fossa.com/projects/git%2Bgithub.com%2Fback-end-labs%2Fruok?ref=badge_shield\u0026issueType=license)\n\n\u003cdiv align=\"center\"\u003e\n    \u003cimg  src=\"./assets/horizontal_logo.png\" alt=\"RUOK Logo\" /\u003e\n\u003c/div\u003e\n\nRUOK Scheduler is an open-source tool designed for hassle-free service monitoring. Keep a close eye on your infrastructure effortlessly with our intuitive scheduler.\n\n- [RUOK Scheduler](#ruok-scheduler)\n  - [1. Introduction](#1-introduction)\n    - [1.1 Purpose](#11-purpose)\n    - [1.2 Why RUOK Scheduler?](#12-why-ruok-scheduler)\n  - [2. Getting Started](#2-getting-started)\n    - [2.1 Building from Source](#21-building-from-source)\n    - [2.2 Preparing the Database](#21-preparing-the-database)\n    - [2.3 Starting RUOK Scheduler](#23-starting-ruok-scheduler)\n  - [3. Configurations](#3-configurations)\n    - [3.1 DB user](#31-db-user)\n    - [3.2 DB Password](#32-db-password)\n    - [3.3 DB Host](#33-db-host)\n    - [3.4 DB Port](#34-db-port)\n    - [3.5 DB Name](#35-db-name)\n    - [3.6 Application Name](#36-application-name)\n    - [3.7 SSL Mode](#37-ssl-mode)\n    - [3.8 Client Cert Password](#38-client-cert-password)\n    - [3.9 Polling Interval](#38-client-cert-password)\n    - [3.10 Max Number of Jobs](#310-max-number-of-jobs)\n  - [4. Job Configuration](#4-job-configuration)\n  - [5. HTTP API](#5-http-api)\n    - [5.1 Create Jobs](#51-create-jobs)\n    - [5.2 Update Jobs](#52-update-jobs)\n    - [5.3 List Jobs](#53-list-jobs)\n    - [5.4 List Job Executions](#54-list-job-executions)\n    - [5.5 Get Instance Info](#55-get-instance-info)\n  - [6. Cron Specification](#6-cron-specification)\n  - [7. License](#7-license)\n\n## 1. Introduction\n\n### 1.1 Purpose\n\nRUOK Scheduler serves the purpose of transforming a PostgreSQL database into a reliable and efficient broker for a backend service monitoring system. It simplifies the process of scheduling and monitoring services, offering a straightforward solution for scenarios where complex deployments are unnecessary.\n\n### 1.2 Why RUOK Scheduler?\n\nIn many cases, deploying and managing monitoring systems can be complex and resource-intensive. RUOK Scheduler aims to address this challenge by providing a simple, yet effective, solution for users who prioritize ease of use and minimal configuration overhead.\n\n## 2. Getting Started\n\n### 2.1 Building from Source\n\nTo build RUOK Scheduler from source, use the following command:\n\n```bash\nmake build\n```\n\nThis will compile and output a single binary named `ruok` in the root directory of this project.\n\nAs the cli is implemented using [cobra](https://github.com/spf13/cobra) you can explore the available commands just by running `./ruok help`, which will output something like the following message:\n\n```sh\n./ruok help\n\n# Turn your postgres database into a backend service monitor.\n# Receive notifications via http, slack, sqs/sns, and much more!\n#\n# Usage:\n#   ruok [flags]\n#   ruok [command]\n#\n# Available Commands:\n#   completion  Generate the autocompletion script for the specified shell\n#   help        Help about any command\n#   setupdb     Runs all migrations needed to setup postgres to work with ruok\n#   start       Starts the scheduler main process\n#   version     Print the version of ruok\n#\n# Flags:\n#   -h, --help   help for ruok\n#\n# Use \"ruok [command] --help\" for more information about a command.\n```\n\n### 2.1 Preparing the Database\n\nBefore running the scheduler you will need to setup a database. This database will store information about the jobs (which endpoints to monitor, what to do in case of failure...) and also a registry of the execution results.\n\nTo migrate the database you will need to run:\n\n```bash\n./ruok setupdb\n```\n\nThis command will do the following:\n\n1. Create a new schema named `ruok`.\n2. Create a function to get a timestamp in microseconds.\n3. Create a function to check TLS status and version.\n4. Create jobs and job_results tables.\n5. Set [Row Security Policies](https://www.postgresql.org/docs/current/ddl-rowsecurity.html) for tables mentioned above.\n6. Create two roles one for the scheduler and one to handle crud operations when using multiple instances of the scheduler.\n\nTo see what resources will be created, please check sql files for the [migrations command](./cmd/migrate/migrations/)\n\nAs this command needs to create and manage several resources, the postgres user/role provided to the cli must the correct permissions.\n\nYou can set those by exporting/using the following envs:\n\n```bash\nexport DB_PASS=correct_pass # Database password (default: password)\nexport DB_USER=correct_user # Database user (default: user)\nexport DB_HOST=your_host    # Database host (default: localhost)\nexport DB_PORT=your_port    # Database port (default: 5432)\nexport DB_NAME=your_db      # Database name (default: db1)\n\n./ruok setupdb\n```\n\n### 2.3 Starting RUOK Scheduler\n\nAgain, make sure you are using a user with correct privileges for this db client.\n\nOur recommendation is to use ruok provided roles. To do it, you must execute the following SQL commands:\n\n```sql\n-- create a new user for ruok\nCREATE ROLE new_ruok_user WITH LOGIN PASSWORD 'ruok_user_pass';\n\n--- set the role created with './ruok migrate'\nGRANT RUOK_SCHEDULER_ROLE TO new_ruok_user;\n```\n\nAfter setting the user, you can run the following commands to start the `ruok`:\n\n```bash\n# use the user created above\nexport DB_USER=ruok_user_pass\n\n# use the pass for the user created above\nexport DB_PASS=new_ruok_user\n\n# use a name to identify this instance\nexport APP_NAME=some_name\nexport DB_HOST=your_host\nexport DB_PORT=your_port\nexport DB_NAME=your_db\n\n./ruok start\n```\n\n## 3 Configurations\n\nAll configurations for RUOK Scheduler are expected as environment variables. Below are the configurations along with their respective environment variables:\n\n### 3.1 DB user\n\nUse this environment to provide a user for the ruok client. We recommend a user with the provided `RUOK_SCHEDULER_ROLE` set, but you can craft your own.\n\n```bash\nDB_PASS                 # Database password (default: password)\n```\n\n### 3.2 DB Password\n\nUse this environment variable to provide the password for the user above.\n\n```bash\nDB_USER                 # Database user (default: user)\n```\n\n### 3.3 DB Host\n\nUse this environment to provide the hostname of your postgres deployment. It will be used by the `ruok` process to interact with it.\n\n```bash\nDB_HOST                 # Database host (default: localhost)\n```\n\n### 3.4 DB Port\n\nUse this environment to provide the port where `ruok` can reach your db.\n\n```bash\nDB_PORT                 # Database port (default: 5432)\n```\n\n### 3.5 DB Name\n\nUse this environment to indicate which db the process needs to interact with.\nMake sure `./ruok setupdb` and `./ruok start` are pointing to the same db.\n\n```bash\nDB_NAME                 # Database name (default: db1)\n```\n\n### 3.6 Application Name\n\nIs recommended to use different application names for different `ruok` processes interacting with the same db. This ensures each process will only mess with their own jobs.\n\nOnly alphanumeric and low dashes are allowed.\n\n```bash\nAPP_NAME                # Application name (default: application1)\n```\n\n### 3.7 SSL Mode\n\nAt the moment we only support `require` and `disable`.\n\n```bash\nDB_SSLMode              # SSL mode for the database (default: disable)\n```\n\nIf `require` is provided, the application expects SSL certificates in `/app` directory with the following names.\n\n```bash\nls /app\n# ca-cert.pem\n# client-cert.pem\n# client-key.pem\n```\n\n### 3.8 Client Cert Password\n\nUse this environment to specify the password for the encryped client key while using SSL for DB connections.\n\n```bash\nDB_SSL_PASS             # SSL password for the database (default: clientpass)\n```\n\n### 3.9 Polling Interval\n\nUse this environment to set how frequent you want the instance to check if there are jobs pending to be claimed.\n\n```bash\nPOLL_INTERVAL_SECONDS   # Polling interval in seconds (default: 60)\n```\n\n### 3.10 Max Number of Jobs\n\nUse this environment to set the maximum amount of jobs the instance can manage.\nAfter setting this, it doesn't matter how many jobs are pending to be claimed, the instance will never exceed this limit.\n\n```bash\nMAX_JOBS                # Maximum number of jobs (default: 10000)\n```\n\n## 4. Job Configuration\n\nIf you are setting jobs for `ruok`, those need specific configurations.\nJobs are stored in `ruok.jobs` table and follows this structure.\n\n```bash\n# A human friendly name to identify the job\njob_name\n\n# The service endpoint to monitor\nendpoint\n\n# The HTTP method to use for monitoring (e.g., GET, POST)\nhttpmethod\n\n# A JSON string containing headers for the HTTP request\nheaders\n\n# An array of HTTP status codes indicating a successful response\nsuccessStatuses\n\n# A cron expression specifying the job schedule\ncronexp\n\n# the channel used to alert in case the service is down (\"http\" at the moment)\nalert_strategy\n\n# the endpoint where alerts must be sent\nalert_endpoint\n\n# http method used to interact with the endpoint above\nalert_method\n\n# a JSON string containing the headers needed\nalert_headers_string\n\n# a string representing the payload to send\nalert_payload\n```\n\n## 5. HTTP API\n\nEach instance of ruok implements an http api to perform common operations.\n\nThe server listens on `http://localhost:8080` by default.\n\n### 5.1 Create Jobs\n\n```bash\n# endpoint\nPOST /v1/jobs\n\n# Example body\n{\n    \"name:\" \"Service 1\",\n    \"cronexp\": \"*/5 * * * * *\",\n    \"maxRetries\": 1,\n    \"endpoint\": \"http://example.com\",\n    \"httpmethod\": \"GET\",\n    \"headers\": \"\",\n    \"successStatuses\": [\n        200,\n        201\n    ],\n    \"alertStrategy\": \"http\",\n    \"alertMethod\": \"POST\",\n    \"alertEndpoint\": \"http://alert.me/now\",\n    \"alertPayload\": \"An error occurred with your endpoint\",\n    \"alertHeaders\": \"\"\n}\n```\n\n### 5.2 Update Jobs\n\n```bash\n# endpoint\nPUT /v1/jobs/:id\n\n# path params\nid --\u003e the id of the job to update\n\n# Example body\n{\n    \"name:\" \"Service 1 - beta\",\n    \"cronexp\": \"*/5 * * * * *\",\n    \"maxRetries\": 1,\n    \"endpoint\": \"http://example.com\",\n    \"httpmethod\": \"GET\",\n    \"headers\": \"\",\n    \"successStatuses\": [\n        200,\n        201\n    ],\n    \"alertStrategy\": \"http\",\n    \"alertMethod\": \"POST\",\n    \"alertEndpoint\": \"http://alert.me/now\",\n    \"alertPayload\": \"An error occurred with your endpoint\",\n    \"alertHeaders\": \"\"\n}\n```\n\n### 5.3 List Jobs\n\n```bash\n# endpoint\nGET /v1/jobs?limit=int\u0026offset=int\n\n# query params\nlimit  --\u003e how many jobs should appear in the result\noffset --\u003e how many should skip\n```\n\n### 5.4 List Job Executions\n\n```bash\n# endpoint\nGET /v1/jobs/:id?limit=int\u0026offset=int\n\n# path params\nid --\u003e the id of the related job\n\n# query params\nlimit  --\u003e how many jobs should appear in the result\noffset --\u003e how many should skip\n```\n\n### 5.5 Get Instance Info\n\n```bash\n# endpoint\nGET /v1/instance\n```\n\n## 6. Cron Specification\n\nRUOK Scheduler uses the [cron expression specification outlined in Wikipedia's CRON expression](https://en.wikipedia.org/wiki/Cron#CRON_expression). Behind the scenes, it leverages the [gorhill/cronexpr package](https://github.com/gorhill/cronexpr) for cron expression handling.\n\n## 7. License\n\nThis software is released under [Apache License 2.0](./LICENSE.md). For more details, refer to the source code and documentation.\n\nFeel free to explore the source code and adapt RUOK Scheduler to meet your specific monitoring needs. If you encounter any issues or have suggestions for improvement, please contribute to the project. Happy monitoring!\n\n_RUOK Scheduler: Simple, Open, Reliable Service Monitoring._\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Flautarojayat%2Fruok","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Flautarojayat%2Fruok","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Flautarojayat%2Fruok/lists"}