watchtower

The Watchtower documentation website is a statically generated hub for user guides, configuration references, and advanced feature documentation. It supports multiple versions of Watchtower to accommodate different releases.

Core Technologies:

• MkDocs: Static site generator using the Material theme.
• Mike: Manages versioned documentation deployment.
• GitHub Actions: Powers automated build and deployment pipelines.

Watchtower operates in two primary modes:

• Full Management (default): Watchtower checks for updates, pulls new images, recreates containers, and runs lifecycle hooks.
• Monitor Only Mode: Watchtower checks for updates, sends notifications, and runs lifecycle hooks, but does not recreate containers.

Watchtower monitors running Docker containers for changes to their original images. When a change is detected, Watchtower pulls the new image, gracefully shuts down the existing container, and restarts it using the exact same options (environment variables, volumes, ports, etc.) used during its initial deployment.

Key Update Logic: Watchtower monitors containers using their exact image reference, including specific tags. It does not automatically jump between different tags.

• Specific Tags: A container running nginx:1.29 will only update if the nginx:1.29 tag itself is updated in the registry. It will not update if nginx:1.30 or nginx:latest is released.
• No Tag (Implicit Latest): A container running myapp (without an explicit tag) will update when the myapp:latest tag changes.

When containers are linked, Watchtower follows a specific sequence to maintain stability:

1. Identify all containers requiring updates.
2. Expand the set to include all containers in the dependency chain.
3. Sort containers using topological order (dependencies first).
4. Stop containers in reverse topological order (dependents first).
5. Update and restart containers in topological order (dependencies first).

Limitation: Rolling restarts are not supported when using linked containers because coordinated updates across dependency chains are required.

When running with default settings, Watchtower performs the following actions:

• Monitoring: It monitors all running containers on the host.
• Polling Interval: It checks for updated image digests every 24 hours.
• Update Process: If an updated image digest is detected, Watchtower will:
  1. Pull the updated container image.
  2. Perform a graceful shutdown of the target container and its dependencies.
  3. Start a new container with the updated image while maintaining the previous container's configuration.

Watchtower v2 will remove legacy notification configuration options for Email, Gotify, Microsoft Teams, and Slack. It is strongly recommended to migrate to using the NOTIFICATION_URL with the appropriate Shoutrrr URL scheme.

To assist with migration:

• Use the Watchtower CLI migration tool to convert legacy email configurations to Shoutrrr URLs.
• Use the Shoutrrr Playground to convert configurations for other services to Shoutrrr URLs.

If you use 2FA on Docker Hub, standard username/password environment variables may not work. Instead, run docker login on your host to generate a $HOME/.docker/config.json file, then mount this file to /config.json inside the Watchtower container.

Important Note on Bind Mounts: Because Docker uses inode-based bind mounts, if the host file is replaced (e.g., by docker login or vim), the container may not see the updates. To ensure changes propagate, consider creating a symlink to your config.json and mounting the symlink instead.

docker run -d \
  --name watchtower \
  -v $HOME/.docker/config.json:/config.json \
  -v /var/run/docker.sock:/var/run/docker.sock \
  --restart unless-stopped \
  nickfedor/watchtower container_to_watch --debug

To run Watchtower as a standalone container via the Docker CLI, use the docker run command. Ensure you mount /var/run/docker.sock to allow Watchtower to interact with the Docker engine.

docker run -d \
--name watchtower \
--restart unless-stopped \
-v /var/run/docker.sock:/var/run/docker.sock \
nickfedor/watchtower

To migrate Gotify, run Watchtower with your current Gotify settings (WATCHTOWER_NOTIFICATION_GOTIFY_URL and WATCHTOWER_NOTIFICATION_GOTIFY_TOKEN).

After running the migration command, replace the settings with a WATCHTOWER_NOTIFICATION_URL in the format: gotify://<URL>/<TOKEN>?title=.

# Example of the new configuration format
services:
  watchtower:
    image: nickfedor/watchtower:latest
    environment:
      WATCHTOWER_NOTIFICATION_URL: "gotify://my.gotify.tld/SuperSecretToken?title="
    volumes:
      - /var/run/docker.sock:/var/run/docker.sock