Watchtower Setup Guide - ajgillis04/GillisDockerDepot GitHub Wiki
Watchtower checks for newer images of your running containers, pulls them, and recreates the containers with the same settings. It has no web page; you control it with environment variables and container labels.
Which image: the original
containrrr/watchtowerwas archived in December 2025 and stopped getting updates. Its old Docker client is also rejected by newer Docker versions (API 1.44 and up), which is why it can silently fail on Windows/WSL and newer Linux hosts. This repository uses the maintained fork,nickfedor/watchtower, which takes the same settings and labels.
compose/serverX/watchtower.yaml, on every server:
services:
watchtower:
container_name: watchtower.${HOST_NAME}
image: nickfedor/watchtower:latest
environment:
TZ: ${TZ}
WATCHTOWER_LABEL_ENABLE: true # only update containers that opt in
WATCHTOWER_CLEANUP: true # delete the old image after each update
WATCHTOWER_INCLUDE_RESTARTING: true
WATCHTOWER_SCHEDULE: "0 0 6 1 * *" # 06:00 on the 1st of every month
WATCHTOWER_NOTIFICATIONS: shoutrrr
WATCHTOWER_NOTIFICATION_URL: discord://${DISCORD_TOKEN}@${DISCORD_ID}
WATCHTOWER_REMOVE_VOLUMES: true
volumes:
- /var/run/docker.sock:/var/run/docker.sock
restart: always
labels:
- "com.centurylinklabs.watchtower.enable=true"WATCHTOWER_SCHEDULE takes seconds first: sec min hour day month weekday. 0 0 6 1 * * means 06:00:00 on the 1st. A five-field value like 0 6 1 * * is read as "second 0, minute 6, hour 1, every day", which runs nightly. Check what it understood in the log:
docker logs watchtower.<host> | grep "Next scheduled run"Without WATCHTOWER_CLEANUP, every update leaves the previous image behind. Over a few months that can reach tens of gigabytes (docker system df shows it under Reclaimable). With it on, Watchtower deletes the old image right after updating. For a one-time cleanup of what's already there, docker image prune removes untagged old versions; check docker images for tagged rollback copies you still want before removing more.
Every service has the label, set to true or false:
labels:
- "com.centurylinklabs.watchtower.enable=true"Turn it off for containers that need care when updating:
- Databases (MySQL, MariaDB): a major version change needs a planned upgrade.
- Containers sharing another's network (Transmission and Soulseek inside Gluetun): recreating one breaks the others. See Gluetun and Transmission Setup Guide.
-
Pinned versions you upgrade on purpose (for example a tool pinned to
v0.11.3).
Images pinned to a version tag only get rebuilds of that same tag. Nextcloud is a good middle ground: pin the major version (nextcloud:34-apache) and let Watchtower apply the 34.x patch releases; move to the next major by hand. See Nextcloud Setup Guide.
Watchtower can't pull from a private registry (such as a private GHCR image) without credentials. Mount a Docker config.json with a login, or turn Watchtower off for those containers and deploy them yourself.
docker exec watchtower.<host> /watchtower --run-onceor update a single container yourself:
docker compose -p mediaserver -f docker-compose-server1.yaml pull <service>
docker compose -p mediaserver -f docker-compose-server1.yaml up -d --no-deps <service>-
Nothing ever updates: check the log for
client version 1.xx is too old. That's the archived image; switch tonickfedor/watchtower. - It runs every night: the schedule has five fields instead of six.
-
Discord messages stop: the webhook was deleted or regenerated; update
DISCORD_IDandDISCORD_TOKENin.env. - A container broke after an update: recreate it from the previous image tag, then turn the label off for it until the problem is fixed upstream.
- WUD (What's Up Docker): web dashboard; can auto-update patch versions and only notify for major ones. Uses its own labels.
- Diun: notifications only, never updates anything.