Watchtower: auto-update Docker containers safely
Watchtower polls your image registries and pulls new versions of your running containers automatically. It's also one of the most reliable ways to break your stack at 4 AM. Here's when to enable it, when to pin tags instead, and how to configure it so updates are useful, not surprising.
The fundamental trade-off
- Pin every image to a specific version. Predictable. Upgrades are a deliberate human action. No surprise breakage. Old vulnerabilities live in your stack until you upgrade.
- Use floating tags + Watchtower. Vulnerability patches arrive fast. Upgrades happen unattended. The cost is that a breaking change shipped by upstream can take your service down with no warning.
Most production self-hosters end up running both patterns on different services. Critical, customer-facing apps are pinned. Stateless utilities (uptime monitors, dashboards, log shippers) auto-update.
The minimum-viable Watchtower
name: watchtower
services:
watchtower:
image: containrrr/watchtower:1.7.1
restart: unless-stopped
volumes:
- /var/run/docker.sock:/var/run/docker.sock
environment:
WATCHTOWER_CLEANUP: "true"
WATCHTOWER_INCLUDE_RESTARTING: "true"
WATCHTOWER_LABEL_ENABLE: "true"
WATCHTOWER_SCHEDULE: "0 0 4 * * *" # 04:00 daily
WATCHTOWER_NOTIFICATION_URL: "telegram://<token>@telegram?chats=<chat_id>"
TZ: Europe/Helsinki
deploy:
resources:
limits:
memory: 128M
Two switches make this safe by default:
WATCHTOWER_LABEL_ENABLE=true— Watchtower only touches containers that explicitly opt in with a label. Default behavior is "update everything," which is exactly what you don't want on a multi-app host.WATCHTOWER_SCHEDULE— cron expression instead of "every 5 minutes." Pick a time when "broken until you wake up" is acceptable; for personal stacks, late at night your timezone.
Opting a service in
services:
uptime-kuma:
image: louislam/uptime-kuma:1 # floating tag — accepts minor updates
restart: unless-stopped
labels:
- "com.centurylinklabs.watchtower.enable=true"
# ... rest of the service
Two pieces have to align:
- The image tag has to be a floating tag (like
:1or:latest), not a specific version. Watchtower compares the digest of the pulled image against the running one — a pinned tag like:1.23.4will never have a new digest, so Watchtower does nothing. - The label opts the container in.
What to auto-update, what to pin
Good candidates for auto-update
- Read-mostly utilities: Uptime Kuma, Glances, Dashy, Homepage.
- Stateless reverse proxies you'd update anyway (Caddy on
:2floats safely within v2). - Log shippers, monitoring agents.
- Personal services where 30 minutes of downtime once a quarter is fine.
Pin these, do not auto-update
- Databases. Postgres major upgrades change data file formats. Watchtower will happily pull
postgres:17over apostgres:16running install and break it. - Application servers with custom configurations that break across versions (n8n major bumps, some Bitwarden flavors).
- Anything that holds money, customer data, or your only copy of important state.
Hybrid pattern
Pin the major version, float within it: caddy:2.8, n8n:1, postgres:16. Watchtower pulls patch and minor updates, which are usually backwards-compatible. You handle major bumps by hand.
Notifications
Watchtower supports email, Slack, Telegram, Discord, Pushover, and generic webhooks via the shoutrrr URL scheme. Telegram is the easiest for individual self-hosters:
WATCHTOWER_NOTIFICATION_URL: "telegram://12345:ABCDE@telegram?chats=987654321"
WATCHTOWER_NOTIFICATIONS_LEVEL: "info"
You want notifications on every update event. The 3 AM "Watchtower updated container X" message is the only proof you have that updates are happening.
Rollbacks
Watchtower has no rollback. When an update breaks something, you pin the image to the previous tag and bring it up by hand:
cd ~/app
# edit docker-compose.yml: replace floating tag with last known good version
docker compose pull
docker compose up -d
To prevent the same broken version from being pulled again, leave the tag pinned until upstream releases a fix. Then re-float.
Watchtower itself
Pin Watchtower's own image (1.7.1, not :latest). A self-updating updater that misbehaves takes the rest of the chain down with it.
Security considerations
- Watchtower needs
/var/run/docker.sockwith write access. The container is therefore as privileged as anything else in thedockergroup — i.e., root-equivalent. Run it on the same host as the things it updates; don't expose it. - If you pull from a private registry, configure
REPO_USERandREPO_PASSor mount a~/.docker/config.json. Treat those credentials carefully. - Pinning to image digests (not just tags) on critical services defends against a compromised registry account:
image: app@sha256:abc....
Alternative: scheduled deploys instead
For team-managed stacks, a simple cron job that runs:
cd /opt/stack
docker compose pull
docker compose up -d
...gives you the same effect as Watchtower with the explicit choice of which files (and therefore which tags) get pulled. Pair with monitoring (Uptime Kuma) so a failed update wakes you up before users notice.
Common Watchtower mistakes
"Watchtower runs but nothing updates"
The image is pinned to an immutable tag. Floating tag required for updates. Or WATCHTOWER_LABEL_ENABLE=true is set but the label is missing on the target container.
"All my containers updated and now half are broken"
You ran with WATCHTOWER_LABEL_ENABLE=false (the default). It pulled latest for everything — including the database, which crossed a major version. Restore from backups. From now on: opt-in via labels, never opt-out.
"Telegram notifications never arrive"
Wrong chat ID format (must be a numeric ID, not a username) or the bot hasn't been messaged once by the chat first. Send /start to your bot from the target chat once.
"Watchtower keeps pulling and restarting in a loop"
Two Watchtower instances are running (perhaps from an earlier docker run) and they're racing. docker ps | grep watchtower, remove the duplicate.
VPS for an auto-updating Docker host?
Watchtower is < 50 MB RAM — adds nothing meaningful to your sizing. Any Inferno plan handles it on top of your existing workload.
What to do next
- Apply Docker hardening — updates only matter if the underlying host is secure.
- Uptime Kuma as the safety net — knows within a minute when an update broke a service.
- Production Compose patterns — healthchecks make Watchtower's restart-on-update actually meaningful.
Author: Riku Lehtinen — Tampere. Last tested: 2026-05-22 on Watchtower 1.7.1, Docker CE 27.3.