Docker Telegram Notifier

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.

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 or reporting a new issue.

Table of contents

• 1. Basic setup
• 2. Advanced setup
  • 2.1 Topics and Threads
  • 2.2 Blacklisting
  • 2.3 Whitelisting
  • 2.4 Per container notifications
  • 2.5 Remote docker instance
• 3. Notification messages customization
  • 3.1 Create a custom template
  • 3.2 Customizing message strings
  • 3.2.1 Default docker event variables
  • 3.2.2 Docker Compose variables
  • 3.2.3 Custom container information in Telegram notifications
• Credits

1. Basic setup

1. Set up a Telegram bot

   • create a Telegram bot and obtain the Bot Token
   • optionally add the bot to a group and allow it to post messages
   • extract the Chat ID

2. Run the container

   using docker-compose.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: <bot_token>
         TELEGRAM_NOTIFIER_CHAT_ID: <chat_id>

   using docker run

   docker run -d \
     --env TELEGRAM_NOTIFIER_BOT_TOKEN=<bot_token> \
     --env TELEGRAM_NOTIFIER_CHAT_ID=<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)

   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 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 section.

2.1 Topics and Threads

Use TELEGRAM_NOTIFIER_TOPIC_ID or TELEGRAM_NOTIFIER_THREAD_ID for specific topics/threads:

services:
  telegram-notifier:
    environment:
      TELEGRAM_NOTIFIER_TOPIC_ID: <topic_id> # optional use only one
      TELEGRAM_NOTIFIER_THREAD_ID: <thread_id> # optional use only one

2.2 Blacklisting

Disable notifications for specific containers:

services:
  example:
    image: hello-world
    labels:
      telegram-notifier.monitor: false

docker run

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:

services:
  telegram-notifier:
    environment:
      ONLY_WHITELIST: true

  example:
    image: hello-world
    labels:
      telegram-notifier.monitor: true

docker run

docker run -d --label telegram-notifier.monitor=true hello-world

2.4 Per container notifications

Configure different channels/threads per container:

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

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.

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 according to your needs.

2. Bind your customized file to the container:

   using docker-compose.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

   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:

container_start: e =>
    `✅ Container Started\n` +
    `Name: <b>${e.Actor.Attributes.name}</b>\n` +
    `Image: <code>${e.Actor.Attributes.image}</code>\n` +
    `ID: <code>${e.Actor.Attributes.container}</code>`

🟢 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:

container_start: e =>
    `✅ Container Started\n` +
    `Project: <b>${e.Actor.Attributes['com.docker.compose.project']}</b>\n` +
    `Service: <b>${e.Actor.Attributes['com.docker.compose.service']}</b> (#${e.Actor.Attributes['com.docker.compose.container-number']})\n` +
    `Image: <code>${e.Actor.Attributes.image}</code>\n` +
    `Compose Version: <code>${e.Actor.Attributes['com.docker.compose.version']}<code>`

🟢 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

   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:

   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:

   container_start: e =>
       `&#9654;&#65039; <b>${e.Actor.Attributes.name}</b> started\n` +
       `Image: <code>${e.Actor.Attributes.image}</code>\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, originally an idea of arefaslani.