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.

Disclosure: contains an affiliate link to Inferno VPS.

The fundamental trade-off

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:

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:

  1. The image tag has to be a floating tag (like :1 or :latest), not a specific version. Watchtower compares the digest of the pulled image against the running one — a pinned tag like :1.23.4 will never have a new digest, so Watchtower does nothing.
  2. The label opts the container in.

What to auto-update, what to pin

Good candidates for auto-update

Pin these, do not auto-update

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

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.

View Inferno plans →

What to do next


Author: Riku Lehtinen — Tampere. Last tested: 2026-05-22 on Watchtower 1.7.1, Docker CE 27.3.