{"id":30722566,"url":"https://github.com/mattmezza/monres","last_synced_at":"2026-05-04T09:05:09.489Z","repository":{"id":299312660,"uuid":"985327312","full_name":"mattmezza/monres","owner":"mattmezza","description":"🪶 Lightweight VPS Resource Monitor. ✉️ Email and 📱 telegram sinks.","archived":false,"fork":false,"pushed_at":"2025-06-15T22:10:45.000Z","size":83,"stargazers_count":1,"open_issues_count":0,"forks_count":0,"subscribers_count":1,"default_branch":"main","last_synced_at":"2025-06-15T23:26:50.200Z","etag":null,"topics":["email","linux","monitor","resource","telegram"],"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/mattmezza.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"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,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null}},"created_at":"2025-05-17T14:29:21.000Z","updated_at":"2025-06-15T22:48:57.000Z","dependencies_parsed_at":"2025-06-15T23:27:01.334Z","dependency_job_id":"aedbba45-c153-47c7-8f1c-37c683cd36bd","html_url":"https://github.com/mattmezza/monres","commit_stats":null,"previous_names":["mattmezza/monres"],"tags_count":1,"template":false,"template_full_name":null,"purl":"pkg:github/mattmezza/monres","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mattmezza%2Fmonres","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mattmezza%2Fmonres/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mattmezza%2Fmonres/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mattmezza%2Fmonres/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/mattmezza","download_url":"https://codeload.github.com/mattmezza/monres/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mattmezza%2Fmonres/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":273431450,"owners_count":25104505,"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-03T02:00:09.631Z","response_time":76,"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":["email","linux","monitor","resource","telegram"],"created_at":"2025-09-03T11:06:52.958Z","updated_at":"2026-05-04T09:05:04.398Z","avatar_url":"https://github.com/mattmezza.png","language":"Go","funding_links":[],"categories":[],"sub_categories":[],"readme":"# monres - Lightweight VPS Resource Monitor\n\n\u003cdiv align=\"center\"\u003e\n    \u003cimg src=\"https://raw.githubusercontent.com/mattmezza/monres/main/icon.png\" alt=\"Monres logo\" width=\"175px\" height=\"175px\"\u003e\n\u003c/div\u003e\n\nmonres is a simple, lightweight, and easy-to-install software tool for monitoring\ncore system resources (CPU, Memory, Disk I/O, Network I/O) on a linux VPS.\nIt runs as a background service, triggers alerts based on user-defined thresholds,\nand sends notifications via Email and Telegram.\n\n## Features\n\n- Monitors CPU, Memory, Disk I/O, Network I/O.\n- Direct OS metric collection (reads `/proc`, `/sys`).\n- Configurable alert rules (threshold, duration, aggregation).\n- Notifications via Email (SMTP) and Telegram.\n- Customizable notification templates.\n- Sensitive credentials read from environment variables.\n- Designed for minimal resource consumption.\n- Single binary deployment (Go).\n- systemd service for management.\n\n## Installation\n\n### Prerequisites\n\n- Go (latest stable version, for building)\n- A linux VPS (tested on Ubuntu)\n\n### Building from Source\n\n1.  Clone the repository:\n    ```bash\n    git clone [https://github.com/mattmezza/monres.git](https://github.com/mattmezza/monres.git)\n    cd monres\n    ```\n\n2.  Build the binary:\n    ```bash\n    go build -ldflags=\"-s -w\" -o monres cmd/monres/main.go\n    ```\n    The `-s -w` flags strip debug information and symbol table, reducing binary size.\n\n3.  Copy the binary to a suitable location:\n    ```bash\n    sudo cp monres /usr/local/bin/\n    ```\n\nFor your convenience, a Makefile is provided.\n\n\n### Configuration\n\n1.  Create the configuration directory:\n    ```bash\n    sudo mkdir -p /etc/monres\n    ```\n\n2.  Copy the example configuration:\n    ```bash\n    sudo cp config.example.yaml /etc/monres/config.yaml\n    ```\n\n3.  Edit `/etc/monres/config.yaml` to suit your needs. Refer to the comments\n    within the file and the \"Configuration Details\" section below.\n\n4.  Create the environment file for sensitive credentials:\n    ```bash\n    sudo touch /etc/monres/monres.env\n    sudo chown monres:monres /etc/monres/monres.env # Assuming 'monres' user/group\n    sudo chmod 600 /etc/monres/monres.env\n    ```\n    Edit `/etc/monres/monres.env` and add your secrets, for example:\n    ```ini\n    MONRES_SMTP_PASSWORD_EMAIL=\"your_smtp_password\"\n    MONRES_TELEGRAM_TOKEN_TELEGRAM=\"your_telegram_bot_token\"\n    ```\n    The environment variable names are constructed as\n    `MONRES_\u003cSENSITIVE_FIELD_UPPERCASE\u003e_\u003cCHANNEL_NAME_UPPERCASE_UNDERSCORED\u003e`.\n    For example, for a channel named `my-email-channel` and field\n    `smtp_password`, the env var would be\n    `MONRES_SMTP_PASSWORD_MY_EMAIL_CHANNEL`.\n\n### Setup as a Systemd Service\n\n1.  Create a dedicated system user for monres:\n    ```bash\n    sudo groupadd --system monres\n    sudo useradd --system --gid monres --shell /sbin/nologin --home-dir /var/lib/monres monres\n    sudo chown -R monres:monres /var/lib/monres\n    # Grant read access to config for the monres user\n    sudo chown root:monres /etc/monres # dir owned by root, group readable by monres\n    sudo chmod 750 /etc/monres\n    sudo chown root:monres /etc/monres/config.yaml\n    sudo chmod 640 /etc/monres/config.yaml\n    # Ensure monres.env is also correctly permissioned and owned as above\n    sudo chown monres:monres /etc/monres/monres.env\n    sudo chmod 600 /etc/monres/monres.env\n    ```\n\n2.  Copy the systemd service file:\n    ```bash\n    sudo cp deploy/systemd/monres.service /etc/systemd/system/\n    ```\n\n3.  Reload systemd, enable, and start the service:\n    ```bash\n    sudo systemctl daemon-reload\n    sudo systemctl enable monres.service\n    sudo systemctl start monres.service\n    ```\n\n4.  Check the status:\n    ```bash\n    sudo systemctl status monres.service\n    journalctl -u monres -f\n    ```\n\n## Configuration Details\n\n- `interval_seconds`: The interval in seconds at which metrics are collected\n  and alerts are evaluated. Default is `1` (every second).\n- `hostname`: The hostname of the VPS, used in notifications.\n  Default is the system's hostname.\n- `alerts`: A list of alert configurations. Each alert has:\n  - `name`: Unique identifier for the alert.\n  - `metric`: The metric to monitor (e.g., `cpu_percent_total`). See below for\n    the full list of metrics.\n  - `threshold`: The threshold value that triggers the alert.\n  - `condition`: The operator for the threshold condition\n    (i.e. `\u003e`, `\u003c`, `\u003e=`, `\u003c=`).\n  - `duration`: The duration over which the metric must exceed the threshold to\n    trigger the alert.\n  - `aggregation`: How to aggregate the metric values (i.e. `avg`, `max`).\n  - `channels`: List of channels to notify when the alert is triggered.\n- `notification_channels`: A list of notification channels. Each channel has:\n    - `type`: The type of channel (i.e. `email`, `telegram`, `stdout`).\n    - `name`: Unique identifier for the channel. This is used to reference the\n      channel in the alerts configuration.\n    - `config`: Configuration specific to the channel type (e.g., SMTP settings\n      for email, bot token for Telegram).\n- `templates`: Customizable notification templates for each alert state (fired\n  or resolved). Each template can include placeholders for dynamic content\n  (e.g., `{{ .AlertName }}`, `{{ .MetricValue }}`). See the example config.\n\n## Metrics Collected\n\n-   `cpu_percent_total`: Total CPU usage percentage.\n-   `mem_percent_used`: Used memory percentage (based on MemAvailable).\n-   `mem_percent_free`: Free memory percentage (based on MemAvailable).\n-   `swap_percent_used`: Used swap percentage.\n-   `swap_percent_free`: Free swap percentage.\n-   `disk_read_bytes_ps`: Aggregated disk read bytes per second.\n-   `disk_write_bytes_ps`: Aggregated disk write bytes per second.\n-   `net_recv_bytes_ps`: Aggregated network received bytes per second.\n-   `net_sent_bytes_ps`: Aggregated network transmitted bytes per second.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmattmezza%2Fmonres","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fmattmezza%2Fmonres","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmattmezza%2Fmonres/lists"}