Migration Tool¶
Overview¶
Watchtower includes a notify-upgrade command to help convert legacy notification configurations to Shoutrrr URLs for use with the NOTIFICATION URL.
It parses legacy Watchtower notification configurations and outputs Shoutrrr URLs to a temporary file inside the Watchtower container.
Usage¶
The notify-upgrade command converts legacy Watchtower notification configurations into Shoutrrr URLs and writes them to a temporary file inside the container.
Running the Command¶
The notify-upgrade can be run either against a Watchtower container that is already running or as a single-run instance that allows you to convert a Docker Compose configuration or Docker CLI flag / environment variable configuration.
Existing Deployment¶
If Watchtower is already deployed and running with your legacy notification configuration, you can execute notify-upgrade directly inside the container:
This works because the Watchtower binary is installed at /watchtower and notify-upgrade is a built-in subcommand.
The common mistake is running docker exec watchtower notify-upgrade, which fails because notify-upgrade is not a standalone executable in $PATH.
Note
Running notify-upgrade inside an existing container does not stop or restart the main Watchtower process.
docker exec runs a separate, short-lived process.
The only side effect is that the notify-upgrade process will stay alive for up to 5 minutes while waiting for you to retrieve the temporary file, after which it cleans up and exits.
Single-Use Run¶
If you have not yet deployed Watchtower or if you want to run notify-upgrade as a one-off command without starting the persistent Watchtower update loop, then run a temporary container configured with notify-upgrade as the command.
services:
watchtower:
image: nickfedor/watchtower:latest
command: notify-upgrade
environment:
WATCHTOWER_NOTIFICATIONS: email
WATCHTOWER_NOTIFICATION_EMAIL_SERVER: smtp.example.com
WATCHTOWER_NOTIFICATION_EMAIL_SERVER_PORT: 587
WATCHTOWER_NOTIFICATION_EMAIL_SERVER_USER: [email protected]
WATCHTOWER_NOTIFICATION_EMAIL_SERVER_PASSWORD: secret
WATCHTOWER_NOTIFICATION_EMAIL_FROM: [email protected]
WATCHTOWER_NOTIFICATION_EMAIL_TO: [email protected]
volumes:
- /var/run/docker.sock:/var/run/docker.sock
docker run --rm \
--name watchtower-notify-upgrade \
-v /var/run/docker.sock:/var/run/docker.sock \
-e WATCHTOWER_NOTIFICATIONS=email \
-e WATCHTOWER_NOTIFICATION_EMAIL_SERVER=smtp.example.com \
-e WATCHTOWER_NOTIFICATION_EMAIL_SERVER_PORT=587 \
-e WATCHTOWER_NOTIFICATION_EMAIL_SERVER_USER=[email protected] \
-e WATCHTOWER_NOTIFICATION_EMAIL_SERVER_PASSWORD=secret \
-e WATCHTOWER_NOTIFICATION_EMAIL_FROM=[email protected] \
-e WATCHTOWER_NOTIFICATION_EMAIL_TO=[email protected] \
nickfedor/watchtower \
notify-upgrade
docker run --rm \
--name watchtower-notify-upgrade \
-v /var/run/docker.sock:/var/run/docker.sock \
nickfedor/watchtower \
notify-upgrade \
--notifications email \
--notification-email-server smtp.example.com \
--notification-email-server-port 587 \
--notification-email-server-user [email protected] \
--notification-email-server-password secret \
--notification-email-from [email protected] \
--notification-email-to [email protected]
services:
watchtower:
image: nickfedor/watchtower:latest
command: notify-upgrade
environment:
WATCHTOWER_NOTIFICATIONS: gotify
WATCHTOWER_NOTIFICATION_GOTIFY_URL: "https://my.gotify.tld/"
WATCHTOWER_NOTIFICATION_GOTIFY_TOKEN: "SuperSecretToken"
WATCHTOWER_NOTIFICATION_GOTIFY_TLS_SKIP_VERIFY: true
volumes:
- /var/run/docker.sock:/var/run/docker.sock
docker run --rm \
--name watchtower-notify-upgrade \
-v /var/run/docker.sock:/var/run/docker.sock \
-e WATCHTOWER_NOTIFICATIONS=gotify \
-e WATCHTOWER_NOTIFICATION_GOTIFY_URL="https://my.gotify.tld/" \
-e WATCHTOWER_NOTIFICATION_GOTIFY_TOKEN="SuperSecretToken" \
-e WATCHTOWER_NOTIFICATION_GOTIFY_TLS_SKIP_VERIFY=true \
nickfedor/watchtower \
notify-upgrade
docker run --rm \
--name watchtower-notify-upgrade \
-v /var/run/docker.sock:/var/run/docker.sock \
nickfedor/watchtower \
notify-upgrade \
--notifications gotify \
--notification-gotify-url "https://my.gotify.tld/" \
--notification-gotify-token "SuperSecretToken" \
--notification-gotify-tls-skip-verify
services:
watchtower:
image: nickfedor/watchtower:latest
command: notify-upgrade
environment:
WATCHTOWER_NOTIFICATIONS: slack
WATCHTOWER_NOTIFICATION_SLACK_HOOK_URL: "https://hooks.slack.com/services/AAA/BBB/CCC"
WATCHTOWER_NOTIFICATION_SLACK_IDENTIFIER: watchtower-server-1
volumes:
- /var/run/docker.sock:/var/run/docker.sock
docker run --rm \
--name watchtower-notify-upgrade \
-v /var/run/docker.sock:/var/run/docker.sock \
-e WATCHTOWER_NOTIFICATIONS=slack \
-e WATCHTOWER_NOTIFICATION_SLACK_HOOK_URL="https://hooks.slack.com/services/AAA/BBB/CCC" \
-e WATCHTOWER_NOTIFICATION_SLACK_IDENTIFIER=watchtower-server-1 \
nickfedor/watchtower \
notify-upgrade
services:
watchtower:
image: nickfedor/watchtower:latest
command: notify-upgrade
environment:
WATCHTOWER_NOTIFICATIONS: msteams
WATCHTOWER_NOTIFICATION_MSTEAMS_HOOK_URL: "https://prod-00.westus.logic.azure.com:443/workflows/abc123/triggers/manual/paths/invoke?api-version=2016-06-00&sp=/triggers/manual/run&sv=1.0&sig=XXXXXXXX"
volumes:
- /var/run/docker.sock:/var/run/docker.sock
docker run --rm \
--name watchtower-notify-upgrade \
-v /var/run/docker.sock:/var/run/docker.sock \
-e WATCHTOWER_NOTIFICATIONS=msteams \
-e WATCHTOWER_NOTIFICATION_MSTEAMS_HOOK_URL="https://prod-00.westus.logic.azure.com:443/workflows/abc123/triggers/manual/paths/invoke?api-version=2016-06-00&sp=/triggers/manual/run&sv=1.0&sig=XXXXXXXX" \
nickfedor/watchtower \
notify-upgrade
docker run --rm \
--name watchtower-notify-upgrade \
-v /var/run/docker.sock:/var/run/docker.sock \
nickfedor/watchtower \
notify-upgrade \
--notifications msteams \
--notification-msteams-hook "https://prod-00.westus.logic.azure.com:443/workflows/abc123/triggers/manual/paths/invoke?api-version=2016-06-00&sp=/triggers/manual/run&sv=1.0&sig=XXXXXXXX"
Important
Replace the example environment variables with your own legacy notification configuration.
The notify-upgrade command inspects the container's current configuration, so it must be started with your legacy notification settings.
Retrieving the Generated File¶
After running notify-upgrade, the converted Shoutrrr URL is written to a temporary file in the container's working directory, with a filename like watchtower-notif-urls-XXXXXX.
The command logs the exact container path and prints a copy command, for example:
INFO To get the environment file, use: docker cp abc123:watchtower-notif-urls-123456789 ./watchtower-notifications.env
Copy it to your local machine with:
The temporary file is automatically removed after 5 minutes or when the container stops, so copy it promptly after generation.
If you are running notify-upgrade as a one-off command (docker run --rm ...), the process will wait up to 5 minutes before exiting.
Before it writes the file, notify-upgrade checks every URL with Shoutrrr, as Watchtower does at startup. If Shoutrrr rejects a URL, such as a Discord webhook whose ID is not a number, notify-upgrade writes no file. Its error never contains the URL. It usually names the service. It cannot when the URL has no scheme or does not parse. The same holds for a URL that ends in an empty # fragment. The error gives a notification URL's position, counting from 1. For a URL converted from a legacy notification type, it names that type instead. Shoutrrr's warnings about a URL, such as a deprecated key, appear in the log.
When the conversion fails, notify-upgrade logs the error and exits with code 1. It removes any file it started to write. If it logs "Failed to remove temporary file" instead, delete the file named in that warning yourself, because it can hold your notification credentials.
Migration Walkthrough¶
Select the tab that matches your legacy notification service.
-
Run the following Docker Compose configuration / Docker CLI command:
services: watchtower: image: nickfedor/watchtower:latest environment: WATCHTOWER_NOTIFICATIONS: email WATCHTOWER_NOTIFICATION_EMAIL_SERVER: smtp.example.com WATCHTOWER_NOTIFICATION_EMAIL_SERVER_PORT: 587 WATCHTOWER_NOTIFICATION_EMAIL_SERVER_USER: [email protected] WATCHTOWER_NOTIFICATION_EMAIL_SERVER_PASSWORD: secret WATCHTOWER_NOTIFICATION_EMAIL_FROM: [email protected] WATCHTOWER_NOTIFICATION_EMAIL_TO: [email protected] volumes: - /var/run/docker.sock:/var/run/docker.sockdocker run -d \ --name watchtower \ -v /var/run/docker.sock:/var/run/docker.sock \ -e WATCHTOWER_NOTIFICATIONS=email \ -e WATCHTOWER_NOTIFICATION_EMAIL_SERVER=smtp.example.com \ -e WATCHTOWER_NOTIFICATION_EMAIL_SERVER_PORT=587 \ -e WATCHTOWER_NOTIFICATION_EMAIL_SERVER_USER=[email protected] \ -e WATCHTOWER_NOTIFICATION_EMAIL_SERVER_PASSWORD=secret \ -e WATCHTOWER_NOTIFICATION_EMAIL_FROM=[email protected] \ -e WATCHTOWER_NOTIFICATION_EMAIL_TO=[email protected] \ nickfedor/watchtowerdocker run -d \ --name watchtower \ -v /var/run/docker.sock:/var/run/docker.sock \ nickfedor/watchtower \ --notifications email \ --notification-email-server smtp.example.com \ --notification-email-server-port 587 \ --notification-email-server-user [email protected] \ --notification-email-server-password secret \ --notification-email-from [email protected] \ --notification-email-to [email protected] -
With the container running, execute the
notify-upgradecommand:Then copy the resulting file out of the container:
-
The following converted Shoutrrr URL should be produced:
smtp://[email protected]:[email protected]:587/[email protected]&[email protected]&encryption=ExplicitTLS&usestarttls=yes -
Replace the deprecated configuration with the coverted Shoutrrr URL:
services: watchtower: image: nickfedor/watchtower:latest environment: WATCHTOWER_NOTIFICATION_URL: smtp://[email protected]:[email protected]:587/[email protected]&[email protected]&encryption=ExplicitTLS&usestarttls=yes WATCHTOWER_NOTIFICATIONS_DELAY: "10" WATCHTOWER_NOTIFICATION_TITLE_TAG: Watchtower volumes: - /var/run/docker.sock:/var/run/docker.sockdocker run -d \ --name watchtower \ -v /var/run/docker.sock:/var/run/docker.sock \ -e "WATCHTOWER_NOTIFICATION_URL=smtp://[email protected]:[email protected]:587/[email protected]&[email protected]&encryption=ExplicitTLS&usestarttls=yes" \ -e WATCHTOWER_NOTIFICATIONS_DELAY=10 \ -e WATCHTOWER_NOTIFICATION_TITLE_TAG=Watchtower \ nickfedor/watchtowerdocker run -d \ --name watchtower \ -v /var/run/docker.sock:/var/run/docker.sock \ nickfedor/watchtower \ --notification-url "smtp://[email protected]:[email protected]:587/[email protected]&[email protected]&encryption=ExplicitTLS&usestarttls=yes" \ --notifications-delay 10 \ --notification-title-tag Watchtower
Note
- Avoid using unrecognized flags like
WATCHTOWER_NOTIFICATION_EMAIL_SERVER_SSL, as they are ignored and may cause confusion. - Use the
encryptionandusestarttlsURL parameters in thesmtp://URL to control TLS behavior rather than deprecated flags.
-
Run the following Docker Compose configuration / Docker CLI command:
services: watchtower: image: nickfedor/watchtower:latest environment: WATCHTOWER_NOTIFICATIONS: gotify WATCHTOWER_NOTIFICATION_GOTIFY_URL: "https://my.gotify.tld/" WATCHTOWER_NOTIFICATION_GOTIFY_TOKEN: "SuperSecretToken" WATCHTOWER_NOTIFICATION_GOTIFY_TLS_SKIP_VERIFY: true volumes: - /var/run/docker.sock:/var/run/docker.sockdocker run -d \ --name watchtower \ -v /var/run/docker.sock:/var/run/docker.sock \ -e WATCHTOWER_NOTIFICATIONS=gotify \ -e WATCHTOWER_NOTIFICATION_GOTIFY_URL="https://my.gotify.tld/" \ -e WATCHTOWER_NOTIFICATION_GOTIFY_TOKEN="SuperSecretToken" \ -e WATCHTOWER_NOTIFICATION_GOTIFY_TLS_SKIP_VERIFY=true \ nickfedor/watchtower -
With the container running, execute the
notify-upgradecommand:Then copy the resulting file out of the container:
-
The following converted Shoutrrr URL should be produced:
-
Replace the deprecated configuration with the coverted Shoutrrr URL:
-
Run the following Docker Compose configuration / Docker CLI command:
services: watchtower: image: nickfedor/watchtower:latest environment: WATCHTOWER_NOTIFICATIONS: slack WATCHTOWER_NOTIFICATION_SLACK_HOOK_URL: "https://hooks.slack.com/services/AAA/BBB/CCC" WATCHTOWER_NOTIFICATION_SLACK_IDENTIFIER: watchtower-server-1 volumes: - /var/run/docker.sock:/var/run/docker.sock```bash docker run -d \ --name watchtower \ -v /var/run/docker.sock:/var/run/docker.sock \ -e WATCHTOWER_NOTIFICATIONS=slack \
-e WATCHTOWER_NOTIFICATION_SLACK_HOOK_URL="https://hooks.slack.com/services/AAA/BBB/CCC" \ -e WATCHTOWER_NOTIFICATION_SLACK_IDENTIFIER=watchtower-server-1 \ nickfedor/watchtower ```
```bash docker run -d \ --name watchtower \ -v /var/run/docker.sock:/var/run/docker.sock \ nickfedor/watchtower \ --notifications slack \ --notification-slack-hook-url "https://hooks.slack.com/services/AAA/BBB/CCC" \
--notification-slack-identifier watchtower-server-1 \ ```
-
With the container running, execute the
notify-upgradecommand:Then copy the resulting file out of the container:
-
The following converted Shoutrrr URL should be produced:
-
Replace the deprecated configuration with the coverted Shoutrrr URL:
-
Run the following Docker Compose configuration / Docker CLI command:
services: watchtower: image: nickfedor/watchtower:latest environment: WATCHTOWER_NOTIFICATIONS: msteams WATCHTOWER_NOTIFICATION_MSTEAMS_HOOK_URL: "https://prod-00.westus.logic.azure.com:443/workflows/abc123/triggers/manual/paths/invoke?api-version=2016-06-00&sp=/triggers/manual/run&sv=1.0&sig=XXXXXXXX" volumes: - /var/run/docker.sock:/var/run/docker.sockdocker run -d \ --name watchtower \ -v /var/run/docker.sock:/var/run/docker.sock \ -e WATCHTOWER_NOTIFICATIONS=msteams \ -e WATCHTOWER_NOTIFICATION_MSTEAMS_HOOK_URL="https://prod-00.westus.logic.azure.com:443/workflows/abc123/triggers/manual/paths/invoke?api-version=2016-06-00&sp=/triggers/manual/run&sv=1.0&sig=XXXXXXXX" \ nickfedor/watchtowerdocker run -d \ --name watchtower \ -v /var/run/docker.sock:/var/run/docker.sock \ nickfedor/watchtower \ --notifications msteams \ --notification-msteams-hook "https://prod-00.westus.logic.azure.com:443/workflows/abc123/triggers/manual/paths/invoke?api-version=2016-06-00&sp=/triggers/manual/run&sv=1.0&sig=XXXXXXXX" -
With the container running, execute the
notify-upgradecommand:Then copy the resulting file out of the container:
-
The following converted Shoutrrr URL should be produced:
-
Replace the deprecated configuration with the coverted Shoutrrr URL:
services: watchtower: image: nickfedor/watchtower:latest environment: WATCHTOWER_NOTIFICATION_URL: "teams://?host=https%3A%2F%2Fprod-00.westus.logic.azure.com%3A443%2Fworkflows%2Fabc123%2Ftriggers%2Fmanual%2Fpaths%2Finvoke%3Fapi-version%3D2016-06-00%26sp%3D%2Ftriggers%2Fmanual%2Frun%26sv%3D1.0%26sig%3DXXXXXXXX&color=%23406170" volumes: - /var/run/docker.sock:/var/run/docker.sockdocker run -d \ --name watchtower \ -v /var/run/docker.sock:/var/run/docker.sock \ -e WATCHTOWER_NOTIFICATION_URL="teams://?host=https%3A%2F%2Fprod-00.westus.logic.azure.com%3A443%2Fworkflows%2Fabc123%2Ftriggers%2Fmanual%2Fpaths%2Finvoke%3Fapi-version%3D2016-06-00%26sp%3D%2Ftriggers%2Fmanual%2Frun%26sv%3D1.0%26sig%3DXXXXXXXX&color=%23406170" \ nickfedor/watchtowerdocker run -d \ --name watchtower \ -v /var/run/docker.sock:/var/run/docker.sock \ nickfedor/watchtower \ --notification-url "teams://?host=https%3A%2F%2Fprod-00.westus.logic.azure.com%3A443%2Fworkflows%2Fabc123%2Ftriggers%2Fmanual%2Fpaths%2Finvoke%3Fapi-version%3D2016-06-00%26sp%3D%2Ftriggers%2Fmanual%2Frun%26sv%3D1.0%26sig%3DXXXXXXXX&color=%23406170"
Automated Migration Script¶
If you have a docker-compose.yaml with a watchtower service configured for legacy notifications, you can use the script below to run the entire migration process end-to-end. It starts the container, executes notify-upgrade, extracts the generated file, prints its contents, and cleans up.
#!/usr/bin/env bash
set -euo pipefail
SERVICE="${1:-watchtower}"
OUTPUT="${2:-./watchtower-notifications.env}"
CONTAINER=$(docker compose run -d "${SERVICE}" notify-upgrade)
trap 'docker rm -f "${CONTAINER}" >/dev/null 2>&1 || true' EXIT
if ! docker ps -q --filter "id=${CONTAINER}" | grep -q .; then
echo "notify-upgrade container exited before producing output. Logs:" >&2
docker logs "${CONTAINER}" >&2 || true
exit 1
fi
FILE=""
TIMEOUT=300
INTERVAL=2
ELAPSED=0
while [[ ${ELAPSED} -lt ${TIMEOUT} ]]; do
FILE=$(docker logs "${CONTAINER}" 2>&1 | grep -oE 'watchtower-notif-urls-[^ ]+' | tail -1 || true)
if [[ -n "${FILE}" ]]; then
break
fi
sleep "${INTERVAL}"
ELAPSED=$((ELAPSED + INTERVAL))
done
if [[ -z "${FILE}" ]]; then
echo "Timed out waiting for notify-upgrade output. Logs:" >&2
docker logs "${CONTAINER}" >/dev/null 2>&1 || true
exit 1
fi
docker cp "${CONTAINER}:${FILE}" "${OUTPUT}"
echo "=== Generated Shoutrrr URL ==="
cat "${OUTPUT}"
Important
- The service must already be defined in
docker-compose.yamlwith your legacy notification environment variables. The script assumes the service name defaults towatchtower. - The command will self-cleanup after 5 minutes or when the script exits.
notify-upgradekeeps a Slack channel only when it is a Slack channel ID, such asC0123456789. A channel name such as#opsor a user such as@alicecannot be carried into the Shoutrrr URL, so the generated URL uses the webhook's own channel andnotify-upgradelogs a warning. Webhooks created by a Slack app always post to their own channel.