Watchtower Telegram notifications

Keeping things up to date can be a hard job. Luckily, software developers are both lazy and focused on simplicity and security. Operating systems, mobile applications, plugins – most of technical stuff can be updated easy today. If you add a docker container via any registry (mostly hub.docker.com), you can pull new releases for the used tag. But this does not restart the container – here comes the Watchtower!

Basic configuration

Watchtower runs as a docker container with access to the docker daemon. Thus it is able to see all running containers including their environments, volumes, ports – and the image name, tag and registry. With the latter information watchtower is able to check for new releases. In the default configuration, watchtower will pull the most recent version of each image, stop existing containers and start the new image with the configuration of the old container. No additional action required 🤯.

I prefer to be notified if something changed, e. g. through an update. I’m already using Telegram for my notifications and would like to be informed if any container got updated/restarted. Watchtower contains a helper named shoutrrr to send notifications via several different channels and applications including Telegram. If you haven’t done yet, create a Telegram bot which is required to send send messages via Telegram. Create a docker-compose file (or add it to an existing one) with the following content:

version: '3.3'

services:
  watchtower:
    image: containrrr/watchtower
    container_name: watchtower
    restart: unless-stopped
    volumes:
      - '/var/run/docker.sock:/var/run/docker.sock'
    environment:
      - TZ=Europe/Berlin
      - WATCHTOWER_LIFECYCLE_HOOKS=1 # Enable pre/post-update scripts
      - WATCHTOWER_NOTIFICATIONS=shoutrrr
      - WATCHTOWER_NOTIFICATION_URL=telegram://$BOT_TOKEN@telegram/?channels=$CHAT_ID

Replace $BOT_TOKEN with your actual token and place any chat id(s) that should receive a message on success/failure. If your configuration is correct, you should receive a message similar to the following one. This message will also be send if watchtower itself gets restarted:

YourBot:
Watchtower 1.3.0
Using notifications: telegram
Checking all containers (except explicitly disabled with label)
Scheduling first run: 2021-08-13 18:19:56 +0200 CEST
Note that the first check will be performed in 23 hours, 59 minutes, 59 seconds

Additional hints

Restart: If an existing (non-updated) container depends on an updated container, all dependent container will be restarted as well. Keep that in mind or simply disable any updates and just get notified. This is not important to me.

Cleanup: In the default configuration, watchtower keeps all tags and versions. After the restart of a container I don’t need the old image. Use the following environment variable to tell watchtower to cleanup after restart.

- WATCHTOWER_CLEANUP=true

Manual built images: Sometimes you don’t use registry images but build your own ones. Watchtower will use the name and tag of the image and try to pull new versions from Docker Hub – which of course leads to an error and a false positive notification in Telegram:

Could not do a head request for "docker_manual-build:latest", falling back to regular pull.
Reason: registry responded to head request with "401 Unauthorized", auth: "Bearer realm=\"https://auth.docker.io/token\",service=\"registry.docker.io\",scope=\"repository:library/docker_manual-build:pull\",error=\"insufficient_scope\""
Unable to update container "/manual-build": Error response from daemon: pull access denied for docker_manual-build, repository does not exist or may require 'docker login': denied: requested access to the resource is denied. Proceeding to next.

To prevent watchtower from attempting to pull those images (or prevent to update any other container, even if it would be able to), add a label to your existing container:

manual-build:
  build: manual-build
  container_name: manual-build
  restart: unless-stopped
  [...]Some config[...]
  labels:
    com.centurylinklabs.watchtower.enable: false

Conclusion

Watchtower reliable updates your container and notifies you about any updates. In combination with shoutrrr notifications to almost any channel – in this case Telegram – are easy as pie 🍰. Hope this helps someone.