Legacy Notification Configuration Option Deprecation

[nicholas-fedor]

Watchtower has supported sending notifications for a long time. This was initially implemented directly within Watchtower; however, eventually split off into a separate project, Shoutrrr. As part of that transition, service-specific configuration options and functionality were reclassified as legacy options. This has led to a number of issues, such as creating long-standing parallel paths for configuring notifications and opening the door for behavioral inconsistencies when using multiple notification services.

Under the hood, Watchtower currently parses legacy configuration options to create URLs for Shoutrrr. This was ultimately meant to be a temporary shim; however, has become a longtime fixture that has diverted Watchtower's users from properly making use of Shoutrrr URLs and the evolving functionality that it provides in its parameter-based approach. Likewise, the presence of this shim limits the addition of further improvements to Watchtower's notifications, such as dynamic notification routing and templates.

As part of the eventual release of the next major release (v2) of Watchtower, deprecation notices and warnings have been implemented to help guide users towards transitioning to using Shoutrrr URLs. I have also begun to make efforts to provide ample documentation, such as through the Watchtower website. Likewise, I have created a (rough, but functional) interactive tool available through the Shoutrrr website, which serves as an alternative to manually downloading and running the Shoutrrr binary or Docker image to to generate URLs.

I highly encourage users of the legacy configuration options to migrate to the use the notification_url configuration option. Additionally, this supports the use of Docker secrets and configuring multiple notification services via a single file (one URL per line).

Given how the legacy configuration options have long been grandfathered into Watchtower, I am attempting to provide ample warning and time for configurations to be updated. Additionally, I welcome any contributions towards improving documentation, such as the Watchtower or Shoutrrr websites, including the Shoutrrr Playground.

[seirdotexe]

For anyone using app passwords in Gmail make sure you remove the spaces 👍

[reibuehl]

I have tried to convert to the new style of email notification configuration but since I converted with docker compose exec watchtower /watchtower notify-upgrade, I don't receive email notifications anymore. What could cause this? Or do I need a new container (shoutrrr ?) to have a basic functionality like email notification now? That would be an additional dependency, so i hope not.

[reibuehl]

I did retrieve the output as described from the container and then added it to my existing docker compose file and commented out the old config:

watchtower:
    image: nickfedor/watchtower
    container_name: watchtower
    command: --cleanup --label-enable
    restart: always
    volumes:
      - /var/run/docker.sock:/var/run/docker.sock
    environment:
      - WATCHTOWER_NOTIFICATIONS_HOSTNAME=<dockerhost>
      - WATCHTOWER_NOTIFICATIONS=email
      - WATCHTOWER_NOTIFICATION_URL=smtp://<mailserver>:25/?auth=None&clienthost=localhost&encryption=None&fromaddress=watchtower%40<dockerhost>&fromname=Watchtower&subject=&toaddresses=<recipient>%40<recipientdomain>&usehtml=No&usestarttls=No&timeout=10s
      # - WATCHTOWER_NOTIFICATION_EMAIL_FROM=watchtower@<dockerhost>
      # - WATCHTOWER_NOTIFICATION_EMAIL_TO=<recipient>@<recipientdomain>
      # - WATCHTOWER_NOTIFICATION_EMAIL_SERVER=<mailserver>
      # - WATCHTOWER_NOTIFICATION_EMAIL_SERVER_TLS_SKIP_VERIFY=true
      - WATCHTOWER_MONITOR_ONLY=false
      - WATCHTOWER_SCHEDULE=0 0 4 * * *
    labels:
      - "com.centurylinklabs.watchtower.enable=true"
      - "com.centurylinklabs.watchtower.monitor-only=false"

[janitor-of-code]

You're still telling it to use the legacy email by setting WATCHTOWER_NOTIFICATIONS=email
nowadays everything is shoutrrr so that line should propably be removed

[janitor-of-code]

I've tried to use your config and after

• turning the URL-encoded @ back to their real selfs
• setting (or removing) &subject=
• removing &clienthost=localhost

got it to working on my end

I assume subject wasn't the issue but all the others seem to be

[reibuehl]

I just tried your first suggestion of removing the WATCHTOWER_NOTIFICATIONS=email and it seems that this alone was enough to get email again. At least the email with "Using notifications: smtp" and the next scheduled run information came. The rest of the options seemed to have been no issue here - the subject of the email is correctly set to "Watchtower updates on " as before.

[nicholas-fedor]

Thanks @janitor-of-code

Yes, using WATCHTOWER_NOTIFICATIONS=email without any corresponding legacy email configuration options results in an initialization failure for Watchtower's notifications process (an empty Shoutrrr SMTP URL is an invalid configuration).