Why Watchtower?
Docker images get security patches, bug fixes, and new features. Without Watchtower, updates are manual:
- Automatic pulls — Detects new images and pulls them.
- Recreates containers — Same config, new image, zero downtime.
- Schedule control — Cron-based timing (e.g., nightly, weekly).
- Per-container policies — Exclude, monitor-only, or auto-update.
- Notifications — Slack, Discord, Telegram, email, Gotify.
- Cleanup — Removes old images after update.
Prerequisites
- Docker on any machine.
- Access to Docker socket.
Deploy Watchtower
docker run -d \
--name watchtower \
--restart=always \
-v /var/run/docker.sock:/var/run/docker.sock \
-e WATCHTOWER_SCHEDULE="0 0 4 * * *" \
-e WATCHTOWER_CLEANUP=true \
-e WATCHTOWER_INCLUDE_STOPPED=true \
containrrr/watchtower
This checks for updates daily at 4 AM.
Update Policies
| Policy | Label / Flag | Behavior |
|---|
| Auto-update (default) | — | Pull + recreate automatically |
| Monitor only | WATCHTOWER_MONITOR_ONLY=true | Notify but don’t update |
| Exclude container | com.centurylinklabs.watchtower.enable=false | Skip this container entirely |
| Include stopped | WATCHTOWER_INCLUDE_STOPPED=true | Update stopped containers too |
| Rolling restart | WATCHTOWER_ROLLING_RESTART=true | One container at a time |
| Cleanup | WATCHTOWER_CLEANUP=true | Remove old images after update |
Notification Channels
| Channel | Environment Variable Example |
|---|
| Slack | WATCHTOWER_NOTIFICATION_URL=slack://hook.slack.com/services/xxx |
| Discord | WATCHTOWER_NOTIFICATION_URL=discord://token@webhookid |
| Telegram | WATCHTOWER_NOTIFICATION_URL=telegram://token@telegram?chats=chatid |
| Email | WATCHTOWER_NOTIFICATION_URL=smtp://user:pass@host:port/?to=you@email.com |
| Gotify | WATCHTOWER_NOTIFICATION_URL=gotify://host/token |
Containers to Exclude (Best Practice)
| Container Type | Why Exclude | Recommended |
|---|
| Databases (Postgres, MySQL, Redis) | Schema migrations, data integrity | Monitor-only |
| Production APIs | Breaking changes, downtime risk | Monitor-only |
| Stateful apps (Nextcloud, GitLab) | Migration steps required | Monitor-only |
| Helper containers (nginx, redis-cache) | Low risk, quick restart | Auto-update |
| Monitoring (Uptime Kuma, Glances) | Low risk | Auto-update |
Troubleshooting
| Problem | Solution |
|---|
| Container not updating | Check it’s not excluded via label; verify image tag isn’t pinned to SHA |
| Private registry auth | Mount ~/.docker/config.json into the Watchtower container |
| Updates happening too often | Switch from latest tag to specific version tags |
| Notification not received | Test the Shoutrrr URL with docker run containrrr/shoutrrr send ... |
Summary
- Set-and-forget Docker container updates on your schedule.
- Per-container control — auto-update, monitor-only, or exclude.
- Multi-channel notifications — know when updates happen.
- Best practice: auto-update stateless tools, monitor-only for databases and stateful apps.
Related Articles