https://github.com/luc-ass/docker-telegram-notifier
Docker container to inform you about docker-events via telegram
https://github.com/luc-ass/docker-telegram-notifier
docker healthcheck notification telegram telegram-bot
Last synced: 5 months ago
JSON representation
Docker container to inform you about docker-events via telegram
- Host: GitHub
- URL: https://github.com/luc-ass/docker-telegram-notifier
- Owner: luc-ass
- License: apache-2.0
- Created: 2022-08-17T16:34:17.000Z (about 3 years ago)
- Default Branch: main
- Last Pushed: 2025-04-25T13:06:30.000Z (6 months ago)
- Last Synced: 2025-04-26T18:58:29.448Z (5 months ago)
- Topics: docker, healthcheck, notification, telegram, telegram-bot
- Language: JavaScript
- Homepage:
- Size: 230 KB
- Stars: 25
- Watchers: 2
- Forks: 9
- Open Issues: 3
-
Metadata Files:
- Readme: README.md
- License: LICENSE
Awesome Lists containing this project
README
# Docker Telegram Notifier
# [](https://github.com/luc-ass/docker-telegram-notifier/actions) [](https://hub.docker.com/r/lorcas/docker-telegram-notifier) [](https://github.com/luc-ass/docker-telegram-notifier/releases) [](https://renovatebot.com)
This 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).
This fork was created to address security vulnerabilities and add support for
- `linux/arm64` and
- `linux/arm/v7` in addition to
- `linux/amd64`.
If 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).
## Table of contents
- [1. Basic setup](#1-basic-setup)
- [2. Advanced setup](#2-advanced-setup)
- [2.1 Topics and Threads](#21-topics-and-threads)
- [2.2 Blacklisting](#22-blacklisting)
- [2.3 Whitelisting](#23-whitelisting)
- [2.4 Per container notifications](#24-per-container-notifications)
- [2.5 Remote docker instance](#25-remote-docker-instance)
- [3. Notification messages customization](#3-notification-messages-customization)
- [3.1 Create a custom template](#31-create-a-custom-template)
- [3.2 Customizing message strings](#32-customizing-message-strings)
- [3.2.1 Default docker event variables](#321-default-docker-event-variables)
- [3.2.2 Docker Compose variables](#322-docker-compose-variables)
- [3.2.3 Custom container information in Telegram notifications](#323-custom-container-information-in-telegram-notifications)
- [Credits](#credits)
## 1. Basic setup
1. **Set up a Telegram bot**
- [create a Telegram bot](https://core.telegram.org/bots#3-how-do-i-create-a-bot) and obtain the Bot Token
- optionally add the bot to a group and allow it to post messages
- extract the [Chat ID](https://stackoverflow.com/a/32572159/882223)
2. **Run the container**
using `docker-compose.yaml`
```yaml
services:
telegram-notifier:
image: lorcas/docker-telegram-notifier:latest
volumes:
- /var/run/docker.sock:/var/run/docker.sock:ro # for local instance
environment:
TELEGRAM_NOTIFIER_BOT_TOKEN:
TELEGRAM_NOTIFIER_CHAT_ID:
```
using `docker run`
```sh
docker run -d \
--env TELEGRAM_NOTIFIER_BOT_TOKEN= \
--env TELEGRAM_NOTIFIER_CHAT_ID= \
--volume /var/run/docker.sock:/var/run/docker.sock:ro \
--hostname my_host \
lorcas/docker-telegram-notifier
```
3. **Add a healthcheck to your container** (optional)
```yaml
example:
image: hello-world
healthcheck:
test: ["CMD", "curl", "-sS", "http://127.0.0.1:8545", "||", "exit", "1"]
interval: 30s
timeout: 10s
retries: 3
```
This setup will start the container and notify you about Docker events. For more advanced configuration, see the [Advanced setup](#2-advanced-setup) section.
## 2. Advanced setup
The 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.
### 2.1 Topics and Threads
Use `TELEGRAM_NOTIFIER_TOPIC_ID` or `TELEGRAM_NOTIFIER_THREAD_ID` for specific topics/threads:
```yaml
services:
telegram-notifier:
environment:
TELEGRAM_NOTIFIER_TOPIC_ID: # optional use only one
TELEGRAM_NOTIFIER_THREAD_ID: # optional use only one
```
### 2.2 Blacklisting
Disable notifications for specific containers:
```yaml
services:
example:
image: hello-world
labels:
telegram-notifier.monitor: false
```
docker run
```sh
docker run -d --label telegram-notifier.monitor=false hello-world
```
### 2.3 Whitelisting
Receive notifications only from whitelisted containers by setting `ONLY_WHITELIST=true` and labeling desired containers:
```yaml
services:
telegram-notifier:
environment:
ONLY_WHITELIST: true
example:
image: hello-world
labels:
telegram-notifier.monitor: true
```
docker run
```sh
docker run -d --label telegram-notifier.monitor=true hello-world
```
### 2.4 Per container notifications
Configure different channels/threads per container:
```yaml
services:
example:
image: hello-world
labels:
# Channel override (optional)
telegram-notifier.chat-id: "-100123456789"
# Thread/Topic override (optional - use only one)
telegram-notifier.topic-id: "12345"
telegram-notifier.thread-id: "12345"
```
docker run
```sh
docker run -d --label telegram-notifier.chat-id=-100123456789 --label telegram-notifier.topic-id=12345 hello-world
```
### 2.5 Remote docker instance
By 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.
Notifier 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`.
A tutorial on how to generate docker certs can be found [here](https://docs.docker.com/engine/security/https/).
```yaml
services:
telegram-notifier:
volumes:
# disable for remote ONLY monitoring
# - /var/run/docker.sock:/var/run/docker.sock:ro
- ./certs:/certs # for remote instance
environment:
DOCKER_HOST: tcp://example.com:2376 # http/https is detected by port number
DOCKER_CERT_PATH: /certs # should contain ca.pem, cert.pem, key.pem
```
## 3. Notification messages customization
### 3.1 Create a custom template
1. __Adapt the template:__ download and modify the message strings from [`templates.js`](./templates.js) according to your needs.
2. __Bind your customized file to the container:__
using `docker-compose.yaml`
```yaml
services:
notifier:
volumes:
# Bind customized file to templates.js in the container:
- ./my-template.js:/usr/src/app/templates.js:ro
environment:
# ...
```
docker run
```sh
docker run -d \
--env TELEGRAM_NOTIFIER_BOT_TOKEN=token \
--env TELEGRAM_NOTIFIER_CHAT_ID=chat_id \
--volume /var/run/docker.sock:/var/run/docker.sock:ro \
--volume ./my-template.js:/usr/src/app/templates.js:ro \
--hostname my_host \
lorcas/docker-telegram-notifier
```
### 3.2 Customizing message strings
### 3.2.1 Default docker event variables
Here are some variables available to customize the notification messages.
| Variable | Description |
| :-------- | :----------- |
| `${e.Actor.Attributes.name}` | Container name |
| `${e.Actor.Attributes.container}` | Container ID |
| `${e.Actor.Attributes.image}` | Container image used |
| `${e.Actor.Attirbutes.exitCode}` | Container exit code |
Example:
```js
container_start: e =>
`✅ Container Started\n` +
`Name: ${e.Actor.Attributes.name}\n` +
`Image: ${e.Actor.Attributes.image}\n` +
`ID: ${e.Actor.Attributes.container}`
```
```
🟢 Container Started
Name: my-container
Image: nginx:latest
ID: abc123def456
```
### 3.2.2 Docker Compose variables
The following variables are only available if the container was started using `docker compose`
| Variable | Description |
| :-------- | :----------- |
| `${e.Actor.Attributes['com.docker.compose.container-number']}` | Compose container Number |
| `${e.Actor.Attributes['com.docker.compose.project']}` | Compose Project Name |
| `${e.Actor.Attributes['com.docker.compose.service']}` | Compose Service Name |
| `${e.Actor.Attributes['com.docker.compose.version']}` | Compose Version |
Example:
```js
container_start: e =>
`✅ Container Started\n` +
`Project: ${e.Actor.Attributes['com.docker.compose.project']}\n` +
`Service: ${e.Actor.Attributes['com.docker.compose.service']} (#${e.Actor.Attributes['com.docker.compose.container-number']})\n` +
`Image: ${e.Actor.Attributes.image}\n` +
`Compose Version: ${e.Actor.Attributes['com.docker.compose.version']}`
```
```
🟢 Container Started
Project: myproject
Service: webserver (#1)
Image: nginx:latest
Compose Version: 2.17.2
```
### 3.2.3 Custom container information in Telegram notifications
Leverage the `labels:` defintion on docker services to make custom information available to notification messages:
1. __Add custom labels to a container:__
using `docker-compose.yaml`
```yaml
services:
example:
image: hello-world
labels:
# Monitor control
telegram-notifier.monitor: true
# Custom defined labels and information
mycustom.telegram.container-info: "Access via http://myhost.com/"
```
using `docker run`:
```sh
docker run -d \
--label "telegram-notifier.monitor=true" \
--label "mycustom.telegram.container-info=Access via http://myhost.com/" \
hello-world
```
2. __Adapt your customized messages template:__
```js
container_start: e =>
`▶️ ${e.Actor.Attributes.name} started\n` +
`Image: ${e.Actor.Attributes.image}\n` +
(
${e.Actor.Attributes['mycustom.telegram.container-info']} ?
`NOTE: ${e.Actor.Attributes['mycustom.telegram.container-info']}` :
''
)
```
## Credits
This 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).