Watchtower

While Watchtower will gracefully update your containers, it will do so automatically without any user intervention. This could potentially lead to problems if an app update introduces breaking changes or requires manual configuration.

You can mitigate this by pinning at-risk applications to specific docker tags ([app_name]_image_version variable), but be aware that doesn’t guarantee immunity from issues.

You can also mitigate risk by keeping regular backups of your application data and configurations. If an update causes issues, you can restore from a backup and handle the update manually.

That said, Watchtower is very convenient for not needing to spend time manually updating containers (and you’ll stay on top of security updates, bug fixes, and new features), just be aware you’re basically YOLOing updates.

A process for automating Docker container base image updates.

Watchtower will pull down your new image, gracefully shut down your existing container and restart it with the same options that were used when it was deployed initially.

Setting up

watchtower_enabled: true

Watchtower will automatically monitor and update all other Docker containers.

Configuration

See the default configuration options for Watchtower at roles/watchtower/defaults/main.yml. Add any overrides to your inventories/[your_inventory]/group_vars/homelab.yml file.

Prometheus metrics

Watchtower can publish metrics (containers scanned/updated/failed/skipped, scan counts) to Prometheus for monitoring. This requires prometheus_enabled: true.

Enable it and set a bearer token Prometheus uses to authenticate — generate one with openssl rand -hex 32:

watchtower_metrics_enabled: true
watchtower_metrics_token: "your-generated-token"
watchtower_ephemeral_self_update_enabled: true

Then import the dashboard from the Watchtower repo’s examples/metrics/grafana/dashboards/dashboard.json to visualize the data.

Recent Changes

Aug 1, 2026

Feat Add optional Prometheus metrics endpoint

Jan 6, 2026

Chore Switch to `nickfedor/watchtower` after original project's archival