{"id":30672686,"url":"https://github.com/cstate/monitorbot","last_synced_at":"2025-09-01T05:06:08.928Z","repository":{"id":312559435,"uuid":"908931058","full_name":"cstate/monitorbot","owner":"cstate","description":"🤖 Automate cState: a Node.js-based monitoring tool that checks the status of websites and services and creates incident reports for your Hugo/cState static site. It's designed to be self-hosted and can deploy incident reports via local file system updates, FTP, or Git. ","archived":false,"fork":false,"pushed_at":"2025-08-31T13:36:53.000Z","size":1342,"stargazers_count":4,"open_issues_count":1,"forks_count":3,"subscribers_count":1,"default_branch":"main","last_synced_at":"2025-08-31T15:32:20.014Z","etag":null,"topics":["bot","cron-jobs","cstate","monitor-bot","monitoring","monitoring-automation","monitoring-tool","node","nodejs","notifications","push","push-notifications","status-page","sysadmin","sysadmin-tool","system-administration-tools","webhooks"],"latest_commit_sha":null,"homepage":"","language":"JavaScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/cstate.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":null,"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,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2024-12-27T10:19:01.000Z","updated_at":"2025-08-31T13:36:57.000Z","dependencies_parsed_at":"2025-09-01T04:30:35.345Z","dependency_job_id":null,"html_url":"https://github.com/cstate/monitorbot","commit_stats":null,"previous_names":["cstate/monitorbot"],"tags_count":null,"template":false,"template_full_name":null,"purl":"pkg:github/cstate/monitorbot","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/cstate%2Fmonitorbot","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/cstate%2Fmonitorbot/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/cstate%2Fmonitorbot/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/cstate%2Fmonitorbot/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/cstate","download_url":"https://codeload.github.com/cstate/monitorbot/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/cstate%2Fmonitorbot/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":273077087,"owners_count":25041357,"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","status":"online","status_checked_at":"2025-09-01T02:00:09.058Z","response_time":120,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"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":["bot","cron-jobs","cstate","monitor-bot","monitoring","monitoring-automation","monitoring-tool","node","nodejs","notifications","push","push-notifications","status-page","sysadmin","sysadmin-tool","system-administration-tools","webhooks"],"created_at":"2025-09-01T05:06:06.708Z","updated_at":"2025-09-01T05:06:08.921Z","avatar_url":"https://github.com/cstate.png","language":"JavaScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# cState MonitorBot\n\nThe cState MonitorBot is a Node.js-based monitoring tool that checks the status of websites and services and creates incident reports for your Hugo/cState static site. It's designed to be self-hosted and can deploy incident reports via local file system updates, FTP, or Git.\n\n## Features\n\n*   **Multiple Check Types:**\n    *   **HTTP(S) Status:** Checks if websites are up and returning the expected HTTP status codes.\n    *   **SSL Certificate:** Monitors SSL certificate validity and expiration dates.\n    *   **DNS Resolution:** Verifies that DNS records are resolving correctly.\n    *   **Port/TCP Connectivity:** Checks if specific ports on a server are reachable.\n    *   **Ping (ICMP):** Measures latency and checks if hosts are reachable via ICMP echo requests.\n*   **Flexible Deployment:**\n    *   **Local:** Updates incident reports directly on the local file system where your Hugo/cState site is located.\n    *   **FTP:** Deploys incident reports to a remote server via FTP.\n    *   **Git:** Commits and pushes incident reports to a Git repository (e.g., GitHub, GitLab).\n*   **Test Mode:** Allows you to run checks and see the results without actually creating or modifying incident files.\n*   **Configurable:** Easily configure the sites to monitor, check intervals, and other settings.\n*   **Color-Coded Output:** Uses `chalk` to provide clear and informative color-coded output in the console.\n*   **Incident Report Format:** Generates incident reports in Markdown format with frontmatter for easy integration with cState.\n*   **Extensible, e.g. for staff notifications (your own)**: Can act as push service for notifications if extended with custom code.\n\n## Requirements\n\n*   **Node.js:** Version 14 or higher (recommended to use the latest LTS version).\n*   **npm:** Usually comes bundled with Node.js.\n*   **Hugo/cState:** You should have a Hugo site set up with cState installed to display the incident reports.\n\n## Installation\n\n1. **Clone the repository:**\n\n```bash\ngit clone https://github.com/cstate/monitorbot.git\ncd monitorbot\n```\n\n2. **Install dependencies:**\n\n```bash\nnpm install\n```\n\n## Configuration\n\n1. **Environment Variables (`.env`):**\n\nCreate a `.env` file in the root of the project and configure the following variables based on your deployment method:\n\n**Local Deployment:**\n\n```\nLOCAL_CSTATE_PATH=../cstate  # Relative path to your Hugo/cState site\n```\n\n**FTP Deployment:**\n\n```\nFTP_HOST=your_ftp_host\nFTP_USER=your_ftp_username\nFTP_PASSWORD=your_ftp_password\nFTP_REMOTE_PATH=/path/to/remote/cstate/content/issues\n```\n\n**Git Deployment:**\n\n```\nGIT_REMOTE=your_git_remote_url (e.g., git@github.com:user/repo.git)\nGIT_BRANCH=main  # Or your default branch\nLOCAL_CSTATE_PATH=../cstate  # Relative path to your Hugo/cState site (for Git, it's used as a working directory)\n```\n\n2. **Configuration File (`config.js`):**\n\nModify the `config.js` file to set up the sites you want to monitor and adjust other settings:\n\n```javascript\nexport default {\n\trunningMethod: 'cron', // 'cron' for continuous process or 'single' for check once and quit\n\tcheckInterval: 5 * 1000, // 5 seconds (adjust as needed), only for cron running method\n\ttestMode: true, // Set to false for actual deployment\n\tdeployment: {\n\tmethod: 'local', // Deployment method: local, ftp, or git\n\t},\n\thttpMonitor: {\n\turls: [\n\t\t{\n\t\tname: \"Example Site\",\n\t\turl: \"https://www.example.com\",\n\t\tfollowRedirect: false, // Follow redirects (default: false)\n\t\texpectStatus: 200, // Expected HTTP status code (default: 200)\n\t\tmethod: 'GET', // HTTP method (default: GET)\n\t\tmaxRedirects: 5, // Maximum number of redirects to follow (default: 5)\n\t\t},\n\t\t// ... more sites\n\t],\n\t},\n\tsslMonitor: {\n\texpirationThresholdDays: 14, // Warn if expiring within 14 days\n\tsites: [\n\t\t{\n\t\tname: \"Example Site\",\n\t\turl: \"https://www.example.com\",\n\t\t},\n\t\t// ... more sites\n\t],\n\t},\n\tdnsMonitor: {\n\tsites: [\n\t\t{\n\t\tname: \"Example Site\",\n\t\turl: \"https://www.example.com\",\n\t\tdnsConfig: {\n\t\t\thost: \"example.com\",\n\t\t\trecordType: \"A\",\n\t\t\texpectedValue: \"93.184.216.34\", // Expected IP\n\t\t},\n\t\t},\n\t\t// ... more sites\n\t],\n\t},\n\tportMonitor: {\n\ttimeout: 5000, // Timeout in milliseconds\n\tsites: [\n\t\t{\n\t\tname: \"Example Site\",\n\t\turl: \"https://www.example.com\",\n\t\tportConfig: {\n\t\t\tport: 80, // Port to check\n\t\t},\n\t\t},\n\t\t// ... more sites\n\t],\n\t},\n\tpingMonitor: {\n\ttimeout: 5, // Timeout in seconds\n\tsites: [\n\t\t{\n\t\tname: \"Example Site\",\n\t\turl: \"https://www.example.com\",\n\t\t},\n\t\t// ... more sites\n\t],\n\t},\n};\n```\n\n## Usage\n\n### Test Mode (Dry Run)\n\nTo run the checks without creating/modifying incident files, make sure `testMode` is set to `true` in `config.js`. Then run:\n\n```bash\nnode index.js\n```\n\nIf you edit the `config.js` file, you will need to restart the script for the changes to take effect.\n\nThis will output the results of the checks to the console in a color-coded format.\n\n### Deployment Mode to Host (Create/Update Incidents)\n\n*   Set `testMode` to `false` in `config.js`.\n*   Choose your deployment method (`local`, `ftp`, or `git`) in `config.js`.\n*   Make sure your `.env` file is configured correctly for your chosen deployment method.\n*   Run:\n\n```bash\nnode index.js\n```\n\nThis will perform the checks and create/update incident Markdown files in your Hugo/cState site based on the results.\n\n#### Scheduling\n\n When the bot uses the `cron` running method, it uses `cron` to run checks periodically. The default interval is set to 60 seconds in `config.js`. You can adjust the `checkInterval` value or modify the cron expression in `index.js` for more advanced scheduling.\n\n**Example (run every 5 minutes):**\n\n```javascript\n// In index.js\nconst job = new CronJob(\n  '0 */5 * * * *', // Cron expression for every 5 minutes\n  runChecks,\n  null,\n  true,\n  'America/Los_Angeles'\n);\n```\n\n### Deployment Mode in GitLab Pipelines *(experimental)*\n\nThis deployment mode relies on the cron scheduler of GitLab pipelines. The bot will run the checks once in the pipeline, perform an issue deployment if necessary and quit. The *incident state* is transferred between pipeline runs using the pipeline cache. \n\n\u003e **Note**: when a cache miss occurs (e.g. due to a network error), the *incident state* is reset, which may result in false positives in your monitor. Deploying the `incident_state.json` every once in a while should make it more reliable, but for simple monitoring tasks using the cache should suffice most of the times.\n\n*   Set `testMode` to `false` and `runningMode` to `single` in `config.js`.\n*   Choose your deployment method (`local`, `ftp`, or `git`) in `config.js`.\n*   Make sure your `.env` file is configured correctly for your chosen deployment method.\n*   When choosing deployment method `git`, make sure to add the git package in the `.gitlab-ci.yml`, by uncommenting the corresponding line.\n\n```yaml\n# In .gitlab-ci.yml\n  before_script:\n    - echo \"Installing dependencies...\"\n    - apk add git  # \u003c-- uncomment this line when using Git deployment method\n    - bun install --no-save\n```\n\n*   In GitLab, schedule a pipeline for this repository for a chosen interval in **Project** \u003e **Build** \u003e **Pipeline schedules**.\n\nOn a small GitLab runner, this pipeline should take about **~20 seconds**, depending on the amount of checks you do.\n\n## Incident Report Format\n\nIncident reports are generated as Markdown files in the `content/issues` directory of your Hugo/cState site. They use the following frontmatter:\n\n```\n---\ntitle: \"Incident Title\"\ndate: 2024-01-10T12:00:00Z\nresolved: false\nsection: issue\nautomated: true\nseverity: \"down\"  # Or \"disrupted\", \"notice\"\naffected: [\"Example Site\"]\nid: \"http-status-example-site\"\n---\n\nIncident description here...\n```\n\n## Contributing\n\nContributions are welcome! If you find a bug or want to add a new feature, please open an issue or submit a pull request.\n\n## License\n\nThis project is licensed under the MIT License.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fcstate%2Fmonitorbot","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fcstate%2Fmonitorbot","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fcstate%2Fmonitorbot/lists"}