{"id":19665240,"url":"https://github.com/alttch/roboger","last_synced_at":"2025-04-28T22:31:08.010Z","repository":{"id":57462341,"uuid":"132197564","full_name":"alttch/roboger","owner":"alttch","description":"Universal event notification broker/manager","archived":false,"fork":false,"pushed_at":"2023-05-20T21:37:18.000Z","size":4184,"stargazers_count":13,"open_issues_count":1,"forks_count":0,"subscribers_count":1,"default_branch":"master","last_synced_at":"2025-04-13T20:16:43.109Z","etag":null,"topics":["broker","email","event","mail","notification","slack","telegram","webhook"],"latest_commit_sha":null,"homepage":"https://roboger.com","language":"Python","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/alttch.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":"2018-05-04T23:17:46.000Z","updated_at":"2023-04-11T15:18:29.000Z","dependencies_parsed_at":"2024-11-11T16:34:09.541Z","dependency_job_id":null,"html_url":"https://github.com/alttch/roboger","commit_stats":{"total_commits":594,"total_committers":4,"mean_commits":148.5,"dds":"0.21380471380471378","last_synced_commit":"c0fe85a8cf2499d1e318dc95fca8e85f89d18279"},"previous_names":[],"tags_count":0,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/alttch%2Froboger","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/alttch%2Froboger/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/alttch%2Froboger/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/alttch%2Froboger/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/alttch","download_url":"https://codeload.github.com/alttch/roboger/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":251397577,"owners_count":21583034,"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":["broker","email","event","mail","notification","slack","telegram","webhook"],"created_at":"2024-11-11T16:21:45.568Z","updated_at":"2025-04-28T22:31:04.354Z","avatar_url":"https://github.com/alttch.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"# What is Roboger?\n\n* Do you like the old good \"echo alarm | sendmail me@mydomain\" trick in crontab?\n* Does your software or servers send you mail/sms alerts when something is\n  wrong?\n* Want to build own notification bot for Telegram, Slack or whatever else?\n* Tired of getting emails from robots?\n\nThen Roboger is definitely for you!\n\nActually nowadays the majority of emails are sent from robots and people don't\nneed to reply. People eventually use emails much less, preferring messengers\nand alternative apps. And we made Roboger - a new generation messenger designed\nspecifically for robots.\n\n![How Roboger works](roboger-scheme.png?raw=true \"How Roboger works\")\n\n# What can Roboger do?\n\n* It can get notifications and forward them to specified endpoints\n* It supports endpoint types: email, JSON webhooks, Slack, Telegram and\n  Roboger Smartphone App (only via https://roboger.com/)\n* It can be easily extended with endpoint plugins\n* This software actually allows you to run your own Roboger server, in case you\n  don't want to use https://roboger.com/, want to have a backup alternative\n\n# Real life example\n\nYou get information messages from your server to Slack, warnings to Slack and\nTelegram, errors to messengers and by mail and on critical events you want to\nadditionally hook API of your PBX to call you on mobile.\n\nIn the past you would have needed to write a code, call APIs, manage event\nrouting and finish in a script hell without any idea what and where notifies\nyou.\n  \nNow you can use Roboger, where everything is already coded, organized and can\nbe set up with a couple of commands.\n\n# How to use\n\nStart Roboger server\n\n```\nroboger-control start\n# launch in front for debugging\nroboger-control launch\n```\n\nThen create address, endpoints and subscriptions with\n[robogerctl](https://github.com/alttch/robogerctl):\n\n```\n\u003e robogerctl address create\nattr    value\n--------------------------------------------------------------------------\nres     9                                                                \u003c\u003c\u003c address resource id\na       5VpTb3jp8yUd138saNnOVDkcTPQBDM9k4kpas2QQW6vZyYr19PvXofmHAfTrkm77 \u003c\u003c\u003c your address\nactive  1\n\n# let's craate endpoint for slack\n\u003e robogerctl endpoint create 9 slack\nattr         value\n--------------------\nres          9.7     \u003c\u003c\u003c endpoint resource id\nactive       1\nconfig       {}\ndescription\nplugin_name  slack\n\n# lets create one subscription for this endpoint\n\u003e robogerctl subscription create 9.7\nattr         value\n---------------------\nres          9.7.16\nactive       1\nendpoint_id  7\nlevel        20\nlevel_match  ge\nlocation\nsender\ntag\n# edit endpoint configuration\n\u003e robogerctl endpoint edit 9.7\n```\nmake sure it looks like\n\n```yaml\nactive: 1\nconfig:\n  url: http://slack-web-hook/url\ndescription: some my chat\n```\n\nThen use Roboger API to send event notifications:\n\n    POST http://your-roboger-host:7719/push \u003c JSON\n    {\n        'addr': 'towhere',\n        'sender': 'from (e.g. from robot1)',\n        'location': 'where something is happened',\n        'tag': 'event tag, eg, serverfail, alarm, achtung',\n        'subject': 'what we are talking about',\n        'msg': 'message body',\n        'level': 'event level (debug, info, warning, error or critical)',\n        'media': 'base64-encoded binary eg. photo from surveillance camera',\n        'media_file': 'media file name'\n    }\n    (all fields except address are optional, default level is \"info\")\n\nOr with **roboger-push** console client in the old good crontab or any other\nsoftware/scripts:\n\n```\necho Everything is down | roboger-push -l warning\n```\n\n**roboger-push** app is written in pure bash, so it will run almost everywhere,\naddresses are defined in /usr/local/etc/roboger_push.ini.\n\nNote: if you want to send media attachments with roboger-push, you should have\nlocal *openssl* CLI installed (it's actually installed everywhere by default,\nwe just warn you about that)\n\n# Python client module\n\nClient module for Python 3: https://github.com/alttch/pyrpush. The module can\nbe installed with pip3:\n\n```\npip3 install pyrpush\n```\n    \nUsage example:\n \n```python\nfrom pyrpush import Client as RPushClient\n\nr = RPushClient()\nr.sender = 'bot1'\nr.location = 'lab'\nr.push('test message')\nr.push(msg='sending you image', media_file='1.jpg', level='warning')\n```\n\nThe module requires **roboger-push** client installed (uses its config only, you\ncan remove *roboger-push* script after the installation)\n\n# Installation\n\n## On the local machine\n\nInstall with pip:\n\n```\npip3 install roboger\npip3 install gunicorn # if not installed\n```\n\nGet sample configuration file from github repo, put it either to\n*/opt/roboger/etc/* or to */usr/local/etc/roboger.yml* or wherever you want and\npoint there ROBOGER_CONFIG env variable.\n\nNote: Roboger database v2 is not compatible with v1. Please reinstall Roboger\nfrom scratch, for the existing resources use auto-deployment.\n\nRoboger can work with SQLite, MySQL and PostgreSQL, however SQLite is not\nrecommended for production due to possible database locks.\n\n## Docker/Kubernetes\n\n* Pre-built image available at https://hub.docker.com/r/altertech/roboger\n* Mount server configuration somewhere and point there ROBOGER_CONFIG env\n  variable\n\n# Installing roboger-push\n\n* log in as root\n* execute the following command: \n\n    *curl -s https://raw.githubusercontent.com/alttch/roboger/master/bin/install-roboger-push | bash /dev/stdin YOUR_ROBOGER_ADDRESS*\n\n* customize /usr/local/etc/roboger_push.ini if required\n\n# Managing\n\nInstall robogerctl (not included in server):\n\n```\npip3 install robogerctl\n```\n\n# Endpoint plugins\n\n## email\n\nSends email notifications\n\nendpoint config:\n\n```json\n{\n  \"rcpt\" : \"some@mail_address\"\n}\n```\n\nserver config:\n\n```yaml\n- name: email\n  config:\n    smtp:\n        host: your-smtp-host # required\n        port: your-smtp-port\n        # tls: true # use tls\n        # ssl: true # use ssl\n        # login: someuser # SMTP server login\n        # password: \"123\" # SMTP server password\n    # default-location: location # if not specified, host name is used\n```\n\n## webhook\n\nSends event web hook HTTP/POST request.\n\nendpoint config:\n\n```json\n{\n  \"url\" : \"http://some.domain/some-webhook-url\",\n  \"template\": \"{ \"event_id\" : $event_id, \"name\": \"value\", \"name2\": \"value2\" }\"\n}\n```\n\nYou may use the following variables in template (quotes for variables are not\nrequired, plugin quotes variables automatically, if necessary):\n\n* **$event_id** event uuid\n* **$addr** event recipient address\n* **$msg** message text\n* **$subject** subject\n* **$formatted_subject** pre-formatted extended subject\n* **$level** level number (10 = DEBUG, 20 = INFO, 30 = WARNING, 40 = ERROR, 50\n  = CRITICAL)\n* **$level_name** level name\n* **$location** event location (if specified)\n* **$tag** event tag (if specified)\n* **$sender** event sender (if specified)\n* **$media** base64-encoded media, if attached\n\nserver config: not required\n\n## shell\n\nExecutes server command, specified in endpoint configuration. The command is\nexecuted with the user permissions of Roboger server process. Should be enabled\nonly in trusted environments, where regular users have no direct access to\nthe endpoint configuration.\n\nendpoint config:\n\n```json\n{\n  \"command\" : \"server shell command\"\n}\n```\n\nVariables: same as in webhook plugin. Variables are sent to command without\nquotes.\n\n## chain\n\nAllows to forward event to another Roboger server. Be careful to avoid event\nloops!\n\nendpoint config:\n\n```json\n{\n  \"url\" : \"http://another-roboger-server\",\n  \"addr\" : \"roboger address on target server\"\n}\n```\n\nNote: */push* uri is not required in \"url\" field.\n\nserver config: not required\n\n## slack\n\nSends notification in Slack.\n\nendpoint config:\n\n```json\n{\n  \"url\" : \"http://some-slack-web-hook.domain/your-webhook-url\",\n  \"rich\": true\n}\n```\n\nIf \"rich\" is true, rich text notification will be sent. Note that this plugin\ndoesn't support attachments.\n\nserver config: not required\n\n## telegram\n\nsends notifications in Telegram\n\nendpoint config:\n\n```json\n{\n  \"chat_id\" : \"encrypted chat id, obtained from roboger bot\"\n}\n```\n\nserver config:\n\n```yaml\n- name: telegram\n  config:\n    token: your-telegram-bot-token\n```\n\nHow it works with Telegram:\n\n* Firstly you need to register your own bot and obtain bot token\n  (https://core.telegram.org/bots#6-botfather)\n* Make sure you have \"url\" param in \"roboger\" section of server config.\n  Telegram plugin uses this param to process and register web hooks.\n* Put bot token to plugin configuration in server config and restart roboger server\n* Find your bot in Telegram and write something to chat\n* Bot will instantly report your encrypted Chat ID.\n\nNote: roboger Chat ID is different from integer Telegram Chat ID. Actually it's\nencrypted with your bot token to avoid people brute forcing chat IDs of shared\nbots.\n\n# Server resources-as-a-code\n\n## Single resource\n\nUse *robogerctl \u003caddr|endpoint|subscription\u003e apply -f file.yml* to apply\nresource configuration.\n\n## Batch\n\nIf you want to deploy in batch, use *robogerctl deploy -f file.yml* command.\nLook *sample-deploy.yml* for deployment example.\n\n## API documentation\n\nSwagger API docs are at http://your-roboger-host:7719/\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Falttch%2Froboger","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Falttch%2Froboger","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Falttch%2Froboger/lists"}