TL;DR — Quick Summary

Watchtower auto-updates Docker containers when new images publish. Configure update schedules, Slack/email notifications, and per-container policies on Linux.

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.