{"id":15645497,"url":"https://github.com/luc-ass/docker-telegram-notifier","last_synced_at":"2025-04-26T18:58:33.463Z","repository":{"id":56811713,"uuid":"525875379","full_name":"luc-ass/docker-telegram-notifier","owner":"luc-ass","description":"Docker container to inform you about docker-events via telegram","archived":false,"fork":false,"pushed_at":"2025-04-25T13:06:30.000Z","size":236,"stargazers_count":25,"open_issues_count":3,"forks_count":9,"subscribers_count":2,"default_branch":"main","last_synced_at":"2025-04-26T18:58:29.448Z","etag":null,"topics":["docker","healthcheck","notification","telegram","telegram-bot"],"latest_commit_sha":null,"homepage":"","language":"JavaScript","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/luc-ass.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,"zenodo":null}},"created_at":"2022-08-17T16:34:17.000Z","updated_at":"2025-04-26T17:02:25.000Z","dependencies_parsed_at":"2023-02-17T03:50:19.636Z","dependency_job_id":"84b15281-c58f-47f3-a47d-fb5579c2cadc","html_url":"https://github.com/luc-ass/docker-telegram-notifier","commit_stats":{"total_commits":128,"total_committers":3,"mean_commits":"42.666666666666664","dds":0.4453125,"last_synced_commit":"07a3f8a7fb12217ac503ca0b1d7c50b5e10a0515"},"previous_names":[],"tags_count":52,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/luc-ass%2Fdocker-telegram-notifier","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/luc-ass%2Fdocker-telegram-notifier/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/luc-ass%2Fdocker-telegram-notifier/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/luc-ass%2Fdocker-telegram-notifier/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/luc-ass","download_url":"https://codeload.github.com/luc-ass/docker-telegram-notifier/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":251038229,"owners_count":21526664,"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":["docker","healthcheck","notification","telegram","telegram-bot"],"created_at":"2024-10-03T12:08:15.649Z","updated_at":"2025-04-26T18:58:33.436Z","avatar_url":"https://github.com/luc-ass.png","language":"JavaScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"\u003c!-- omit in toc --\u003e\n# Docker Telegram Notifier\n\u003c!-- omit in toc --\u003e\n# [![GitHub Workflow Status](https://img.shields.io/github/actions/workflow/status/luc-ass/docker-telegram-notifier/docker-image.yml?branch=main\u0026style=for-the-badge)](https://github.com/luc-ass/docker-telegram-notifier/actions) [![Docker Pulls](https://img.shields.io/docker/pulls/lorcas/docker-telegram-notifier?logo=docker\u0026style=for-the-badge)](https://hub.docker.com/r/lorcas/docker-telegram-notifier) [![Docker Image Version (latest semver)](https://img.shields.io/docker/v/lorcas/docker-telegram-notifier?logo=docker\u0026style=for-the-badge)](https://github.com/luc-ass/docker-telegram-notifier/releases) [![Renovate](https://img.shields.io/badge/renovate-enabled-green?style=for-the-badge\u0026logo=data:image/svg+xml;base64,PHN2ZyB4bWxucz0iaHR0cDovL3d3dy53My5vcmcvMjAwMC9zdmciIHZpZXdCb3g9IjUgNSAzNzAgMzcwIj48Y2lyY2xlIGN4PSIxODkiIGN5PSIxOTAiIHI9IjE4NCIgZmlsbD0iI2ZlMiIvPjxwYXRoIGZpbGw9IiM4YmIiIGQ9Ik0yNTEgMjU2bC0zOC0zOGExNyAxNyAwIDAxMC0yNGw1Ni01NmMyLTIgMi02IDAtN2wtMjAtMjFhNSA1IDAgMDAtNyAwbC0xMyAxMi05LTggMTMtMTNhMTcgMTcgMCAwMTI0IDBsMjEgMjFjNyA3IDcgMTcgMCAyNGwtNTYgNTdhNSA1IDAgMDAwIDdsMzggMzh6Ii8+PHBhdGggZmlsbD0iI2Q1MSIgZD0iTTMwMCAyODhsLTggOGMtNCA0LTExIDQtMTYgMGwtNDYtNDZjLTUtNS01LTEyIDAtMTZsOC04YzQtNCAxMS00IDE1IDBsNDcgNDdjNCA0IDQgMTEgMCAxNXoiLz48cGF0aCBmaWxsPSIjYjMwIiBkPSJNMjg1IDI1OGw3IDdjNCA0IDQgMTEgMCAxNWwtOCA4Yy00IDQtMTEgNC0xNiAwbC02LTdjNCA1IDExIDUgMTUgMGw4LTdjNC01IDQtMTIgMC0xNnoiLz48cGF0aCBmaWxsPSIjYTMwIiBkPSJNMjkxIDI2NGw4IDhjNCA0IDQgMTEgMCAxNmwtOCA3Yy00IDUtMTEgNS0xNSAwbC05LThjNSA1IDEyIDUgMTYgMGw4LThjNC00IDQtMTEgMC0xNXoiLz48cGF0aCBmaWxsPSIjZTYyIiBkPSJNMjYwIDIzM2wtNC00Yy02LTYtMTctNi0yMyAwLTcgNy03IDE3IDAgMjRsNCA0Yy00LTUtNC0xMSAwLTE2bDgtOGM0LTQgMTEtNCAxNSAweiIvPjxwYXRoIGZpbGw9IiNiNDAiIGQ9Ik0yODQgMzA0Yy00IDAtOC0xLTExLTRsLTQ3LTQ3Yy02LTYtNi0xNiAwLTIybDgtOGM2LTYgMTYtNiAyMiAwbDQ3IDQ2YzYgNyA2IDE3IDAgMjNsLTggOGMtMyAzLTcgNC0xMSA0em0tMzktNzZjLTEgMC0zIDAtNCAybC04IDdjLTIgMy0yIDcgMCA5bDQ3IDQ3YTYgNiAwIDAwOSAwbDctOGMzLTIgMy02IDAtOWwtNDYtNDZjLTItMi0zLTItNS0yeiIvPjxwYXRoIGZpbGw9IiMxY2MiIGQ9Ik0xNTIgMTEzbDE4LTE4IDE4IDE4LTE4IDE4em0xLTM1bDE4LTE4IDE4IDE4LTE4IDE4em0tOTAgODlsMTgtMTggMTggMTgtMTggMTh6bTM1LTM2bDE4LTE4IDE4IDE4LTE4IDE4eiIvPjxwYXRoIGZpbGw9IiMxZGQiIGQ9Ik0xMzQgMTMxbDE4LTE4IDE4IDE4LTE4IDE4em0tMzUgMzZsMTgtMTggMTggMTgtMTggMTh6Ii8+PHBhdGggZmlsbD0iIzJiYiIgZD0iTTExNiAxNDlsMTgtMTggMTggMTgtMTggMTh6bTU0LTU0bDE4LTE4IDE4IDE4LTE4IDE4em0tODkgOTBsMTgtMTggMTggMTgtMTggMTh6bTEzOS04NWwyMyAyM2M0IDQgNCAxMSAwIDE2TDE0MiAyNDBjLTQgNC0xMSA0LTE1IDBsLTI0LTI0Yy00LTQtNC0xMSAwLTE1bDEwMS0xMDFjNS01IDEyLTUgMTYgMHoiLz48cGF0aCBmaWxsPSIjM2VlIiBkPSJNMTM0IDk1bDE4LTE4IDE4IDE4LTE4IDE4em0tNTQgMThsMTgtMTcgMTggMTctMTggMTh6bTU1LTUzbDE4LTE4IDE4IDE4LTE4IDE4em05MyA0OGwtOC04Yy00LTUtMTEtNS0xNiAwTDEwMyAyMDFjLTQgNC00IDExIDAgMTVsOCA4Yy00LTQtNC0xMSAwLTE1bDEwMS0xMDFjNS00IDEyLTQgMTYgMHoiLz48cGF0aCBmaWxsPSIjOWVlIiBkPSJNMjcgMTMxbDE4LTE4IDE4IDE4LTE4IDE4em01NC01M2wxOC0xOCAxOCAxOC0xOCAxOHoiLz48cGF0aCBmaWxsPSIjMGFhIiBkPSJNMjMwIDExMGwxMyAxM2M0IDQgNCAxMSAwIDE2TDE0MiAyNDBjLTQgNC0xMSA0LTE1IDBsLTEzLTEzYzQgNCAxMSA0IDE1IDBsMTAxLTEwMWM1LTUgNS0xMSAwLTE2eiIvPjxwYXRoIGZpbGw9IiMxYWIiIGQ9Ik0xMzQgMjQ4Yy00IDAtOC0yLTExLTVsLTIzLTIzYTE2IDE2IDAgMDEwLTIzTDIwMSA5NmExNiAxNiAwIDAxMjIgMGwyNCAyNGM2IDYgNiAxNiAwIDIyTDE0NiAyNDNjLTMgMy03IDUtMTIgNXptNzgtMTQ3bC00IDItMTAxIDEwMWE2IDYgMCAwMDAgOWwyMyAyM2E2IDYgMCAwMDkgMGwxMDEtMTAxYTYgNiAwIDAwMC05bC0yNC0yMy00LTJ6Ii8+PC9zdmc+)](https://renovatebot.com)\n\n\nThis Docker container provides a Telegram integration to notify you about Docker events. It can notify you when a container starts, stops (including details about exit codes), restarts, and when the healthcheck status of a Docker container changes. You have the flexibility to customize these notifications by [modifying the `templates.js` file](#3-notification-messages-customization).\n\nThis fork was created to address security vulnerabilities and add support for \n- `linux/arm64` and\n- `linux/arm/v7` in addition to\n- `linux/amd64`.\n\nIf you encounter any issues, please feel free to contribute by fixing them and opening a [pull request](https://github.com/luc-ass/docker-telegram-notifier/pulls) or reporting a new [issue](https://github.com/luc-ass/docker-telegram-notifier/issues).\n\n\u003c!-- omit in toc --\u003e\n## Table of contents\n- [1. Basic setup](#1-basic-setup)\n- [2. Advanced setup](#2-advanced-setup)\n  - [2.1 Topics and Threads](#21-topics-and-threads)\n  - [2.2 Blacklisting](#22-blacklisting)\n  - [2.3 Whitelisting](#23-whitelisting)\n  - [2.4 Per container notifications](#24-per-container-notifications)\n  - [2.5 Remote docker instance](#25-remote-docker-instance)\n- [3. Notification messages customization](#3-notification-messages-customization)\n  - [3.1 Create a custom template](#31-create-a-custom-template)\n  - [3.2 Customizing message strings](#32-customizing-message-strings)\n  - [3.2.1 Default docker event variables](#321-default-docker-event-variables)\n  - [3.2.2 Docker Compose variables](#322-docker-compose-variables)\n  - [3.2.3 Custom container information in Telegram notifications](#323-custom-container-information-in-telegram-notifications)\n- [Credits](#credits)\n\n\n## 1. Basic setup  \n\n1. **Set up a Telegram bot**\n\n    - [create a Telegram bot](https://core.telegram.org/bots#3-how-do-i-create-a-bot) and obtain the Bot Token\n    - optionally add the bot to a group and allow it to post messages\n    - extract the [Chat ID](https://stackoverflow.com/a/32572159/882223)\n\n2. **Run the container**\n\n    using `docker-compose.yaml`\n    ```yaml\n    services:\n      telegram-notifier:\n        image: lorcas/docker-telegram-notifier:latest\n        volumes:\n            - /var/run/docker.sock:/var/run/docker.sock:ro # for local instance\n        environment:\n          TELEGRAM_NOTIFIER_BOT_TOKEN: \u003cbot_token\u003e\n          TELEGRAM_NOTIFIER_CHAT_ID: \u003cchat_id\u003e\n    ```\n\n    using `docker run`\n    ```sh\n    docker run -d \\\n      --env TELEGRAM_NOTIFIER_BOT_TOKEN=\u003cbot_token\u003e \\\n      --env TELEGRAM_NOTIFIER_CHAT_ID=\u003cchat_id\u003e \\\n      --volume /var/run/docker.sock:/var/run/docker.sock:ro \\\n      --hostname my_host \\\n      lorcas/docker-telegram-notifier\n    ```\n\n3. **Add a healthcheck to your container** (optional)\n   \n    ```yaml\n    example:\n      image: hello-world\n      healthcheck:\n        test: [\"CMD\", \"curl\", \"-sS\", \"http://127.0.0.1:8545\", \"||\", \"exit\", \"1\"]\n        interval: 30s\n        timeout: 10s\n        retries: 3\n    ```\n\nThis setup will start the container and notify you about Docker events. For more advanced configuration, see the [Advanced setup](#2-advanced-setup) section.\n\n\n## 2. Advanced setup\n\nThe following options are available to customize the behavior of the notifier. Examples are provided for `docker-compose.yaml` but are also applicable to `docker run`. Only the changes are shown, make sure to include the rest from the [Basic setup](#1-basic-setup) section.\n\n### 2.1 Topics and Threads\n\nUse `TELEGRAM_NOTIFIER_TOPIC_ID` or `TELEGRAM_NOTIFIER_THREAD_ID` for specific topics/threads:\n\n```yaml\nservices:\n  telegram-notifier:\n    environment:\n      TELEGRAM_NOTIFIER_TOPIC_ID: \u003ctopic_id\u003e # optional use only one\n      TELEGRAM_NOTIFIER_THREAD_ID: \u003cthread_id\u003e # optional use only one\n```\n\n### 2.2 Blacklisting\nDisable notifications for specific containers:\n\n\n```yaml\nservices:\n  example:\n    image: hello-world\n    labels:\n      telegram-notifier.monitor: false\n```\n\n\u003cdetails\u003e\n\u003csummary\u003e\ndocker run\n\u003c/summary\u003e\n\n```sh\ndocker run -d --label telegram-notifier.monitor=false hello-world\n```\n\u003c/details\u003e\n\n\n### 2.3 Whitelisting\n\nReceive notifications only from whitelisted containers by setting `ONLY_WHITELIST=true` and labeling desired containers:\n\n```yaml\nservices:\n  telegram-notifier:\n    environment:\n      ONLY_WHITELIST: true\n\n  example:\n    image: hello-world\n    labels:\n      telegram-notifier.monitor: true\n```\n\u003cdetails\u003e\n\u003csummary\u003e\ndocker run\n\u003c/summary\u003e\n\n```sh\ndocker run -d --label telegram-notifier.monitor=true hello-world\n```\n\u003c/details\u003e\n\n### 2.4 Per container notifications\n\nConfigure different channels/threads per container:\n\n```yaml\nservices:\n  example:\n    image: hello-world\n    labels:\n      # Channel override (optional)\n      telegram-notifier.chat-id: \"-100123456789\"\n      # Thread/Topic override (optional - use only one)\n      telegram-notifier.topic-id: \"12345\"\n      telegram-notifier.thread-id: \"12345\"\n```\n\n\u003cdetails\u003e\n\u003csummary\u003e\ndocker run\n\u003c/summary\u003e\n\n```sh\ndocker run -d --label telegram-notifier.chat-id=-100123456789 --label telegram-notifier.topic-id=12345 hello-world\n```\n\u003c/details\u003e\n\n\n### 2.5 Remote docker instance\n\nBy default notifier connects to a local docker instance (don't forget to specify `--volume /var/run/docker.sock:/var/run/docker.sock:ro` for this case). But if you have monitoring and the service on the same host, you will not receive notifications if the host goes down. So I recommend to have monitoring separately.\n\nNotifier accepts usual `DOCKER_HOST` and `DOCKER_CERT_PATH` environment variables to specify remote instance. For http endpoint you need to specify only `--env DOCKER_HOST=tcp://example.com:2375` (make sure to keep such instances behind the firewall). For https, you'll also need to mount a volume with https certificates that contains `ca.pem`, `cert.pem`, and `key.pem`: `--env DOCKER_HOST=tcp://example.com:2376 --env DOCKER_CERT_PATH=/certs --volume $(pwd):/certs`.\nA tutorial on how to generate docker certs can be found [here](https://docs.docker.com/engine/security/https/).\n\n```yaml\nservices:\n  telegram-notifier:\n    volumes:\n      # disable for remote ONLY monitoring\n      # - /var/run/docker.sock:/var/run/docker.sock:ro \n      - ./certs:/certs # for remote instance\n    environment:\n      DOCKER_HOST: tcp://example.com:2376 # http/https is detected by port number\n      DOCKER_CERT_PATH: /certs # should contain ca.pem, cert.pem, key.pem\n```\n\n\n## 3. Notification messages customization\n\n### 3.1 Create a custom template\n\n1. __Adapt the template:__ download and modify the message strings from [`templates.js`](./templates.js) according to your needs.\n\n2. __Bind your customized file to the container:__\n\n    using `docker-compose.yaml`\n    ```yaml\n    services:\n      notifier:\n        volumes:\n          # Bind customized file to templates.js in the container:\n          - ./my-template.js:/usr/src/app/templates.js:ro\n        environment:\n          # ...\n    ```\n\n    \u003cdetails\u003e\n    \u003csummary\u003e\n    docker run\n    \u003c/summary\u003e\n\n    ```sh\n    docker run -d \\\n        --env TELEGRAM_NOTIFIER_BOT_TOKEN=token \\\n        --env TELEGRAM_NOTIFIER_CHAT_ID=chat_id \\\n        --volume /var/run/docker.sock:/var/run/docker.sock:ro \\\n        --volume ./my-template.js:/usr/src/app/templates.js:ro \\\n        --hostname my_host \\\n        lorcas/docker-telegram-notifier\n    ```\n    \u003c/details\u003e\n\n### 3.2 Customizing message strings\n\n### 3.2.1 Default docker event variables\n\nHere are some variables available to customize the notification messages.\n\n| Variable | Description |\n| :-------- | :----------- |\n| `${e.Actor.Attributes.name}` | Container name |\n| `${e.Actor.Attributes.container}` | Container ID |\n| `${e.Actor.Attributes.image}` | Container image used |\n| `${e.Actor.Attirbutes.exitCode}` | Container exit code |\n\nExample:\n```js\ncontainer_start: e =\u003e\n    `\u0026#9989; Container Started\\n` +\n    `Name: \u003cb\u003e${e.Actor.Attributes.name}\u003c/b\u003e\\n` +\n    `Image: \u003ccode\u003e${e.Actor.Attributes.image}\u003c/code\u003e\\n` +\n    `ID: \u003ccode\u003e${e.Actor.Attributes.container}\u003c/code\u003e`\n```\n```\n🟢 Container Started\nName: my-container\nImage: nginx:latest\nID: abc123def456\n```\n\n\n### 3.2.2 Docker Compose variables\n\nThe following variables are only available if the container was started using `docker compose`\n| Variable | Description |\n| :-------- | :----------- |\n| `${e.Actor.Attributes['com.docker.compose.container-number']}` | Compose container Number |\n| `${e.Actor.Attributes['com.docker.compose.project']}` | Compose Project Name |\n| `${e.Actor.Attributes['com.docker.compose.service']}` | Compose Service Name |\n| `${e.Actor.Attributes['com.docker.compose.version']}` | Compose Version |\n\nExample:\n```js\ncontainer_start: e =\u003e\n    `\u0026#9989; Container Started\\n` +\n    `Project: \u003cb\u003e${e.Actor.Attributes['com.docker.compose.project']}\u003c/b\u003e\\n` +\n    `Service: \u003cb\u003e${e.Actor.Attributes['com.docker.compose.service']}\u003c/b\u003e (#${e.Actor.Attributes['com.docker.compose.container-number']})\\n` +\n    `Image: \u003ccode\u003e${e.Actor.Attributes.image}\u003c/code\u003e\\n` +\n    `Compose Version: \u003ccode\u003e${e.Actor.Attributes['com.docker.compose.version']}\u003ccode\u003e`\n```\n```\n🟢 Container Started\nProject: myproject\nService: webserver (#1)\nImage: nginx:latest\nCompose Version: 2.17.2\n```\n\n### 3.2.3 Custom container information in Telegram notifications\n\nLeverage the `labels:` defintion on docker services to make custom information available to notification messages:\n\n1. __Add custom labels to a container:__\n\n    using `docker-compose.yaml`\n    ```yaml\n    services:\n      example:\n        image: hello-world\n        labels:\n          # Monitor control\n          telegram-notifier.monitor: true\n          # Custom defined labels and information\n          mycustom.telegram.container-info: \"Access via http://myhost.com/\"\n    ```\n\n    using `docker run`:\n    ```sh\n    docker run -d \\\n        --label \"telegram-notifier.monitor=true\" \\\n        --label \"mycustom.telegram.container-info=Access via http://myhost.com/\" \\\n        hello-world\n    ```\n\n\n2. __Adapt your customized messages template:__\n    ```js\n    container_start: e =\u003e\n        `\u0026#9654;\u0026#65039; \u003cb\u003e${e.Actor.Attributes.name}\u003c/b\u003e started\\n` +\n        `Image: \u003ccode\u003e${e.Actor.Attributes.image}\u003c/code\u003e\\n` +\n        (\n          ${e.Actor.Attributes['mycustom.telegram.container-info']} ?\n          `NOTE: ${e.Actor.Attributes['mycustom.telegram.container-info']}` :\n          ''\n        )\n    ```\n\n## Credits\n\nThis container is based on the [container by poma](https://hub.docker.com/r/poma/docker-telegram-notifier), originally an idea of [arefaslani](https://github.com/arefaslani).\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fluc-ass%2Fdocker-telegram-notifier","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fluc-ass%2Fdocker-telegram-notifier","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fluc-ass%2Fdocker-telegram-notifier/lists"}