Watchtower Setup Guide - ajgillis04/GillisDockerDepot GitHub Wiki

Watchtower Setup Guide

Introduction

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/watchtower was 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.

How It's Set Up Here

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"

The schedule has six fields

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"

Old images pile up without cleanup

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.

Opting containers in and out

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.

Private images

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.

Running It Now (Outside the Schedule)

docker exec watchtower.<host> /watchtower --run-once

or 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>

Troubleshooting

  • Nothing ever updates: check the log for client version 1.xx is too old. That's the archived image; switch to nickfedor/watchtower.
  • It runs every night: the schedule has five fields instead of six.
  • Discord messages stop: the webhook was deleted or regenerated; update DISCORD_ID and DISCORD_TOKEN in .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.

Alternatives

  • 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.
⚠️ **GitHub.com Fallback** ⚠️