Watchtower: Automatic Docker Container Updates

Watchtower monitors your running Docker containers and automatically updates them when new images are available in the registry. It pulls the latest image, gracefully stops the running container, and restarts it with the same configuration. This guide covers deployment, configuration, and safe update strategies.

Quick Start

docker run -d --name watchtower \
    -v /var/run/docker.sock:/var/run/docker.sock \
    containrrr/watchtower

Docker Compose

services:
  watchtower:
    image: containrrr/watchtower
    container_name: watchtower
    restart: always
    volumes:
      - /var/run/docker.sock:/var/run/docker.sock
    environment:
      - WATCHTOWER_POLL_INTERVAL=3600        # Check every hour
      - WATCHTOWER_CLEANUP=true              # Remove old images
      - WATCHTOWER_INCLUDE_STOPPED=false     # Skip stopped containers
      - WATCHTOWER_NOTIFICATIONS=email
      - WATCHTOWER_NOTIFICATION_EMAIL_FROM=watchtower@example.com
      - WATCHTOWER_NOTIFICATION_EMAIL_TO=admin@example.com
      - WATCHTOWER_NOTIFICATION_EMAIL_SERVER=smtp.example.com
      - WATCHTOWER_NOTIFICATION_EMAIL_SERVER_PORT=587
      - WATCHTOWER_NOTIFICATION_EMAIL_SERVER_USER=user
      - WATCHTOWER_NOTIFICATION_EMAIL_SERVER_PASSWORD=pass

Selective Updates

# Only update specific containers (by label)
docker run -d --label com.centurylinklabs.watchtower.enable=true --name web nginx
docker run -d --label com.centurylinklabs.watchtower.enable=false --name db postgres

# Watchtower with label filter
docker run -d --name watchtower \
    -v /var/run/docker.sock:/var/run/docker.sock \
    containrrr/watchtower --label-enable

# Or specify container names
docker run -d --name watchtower \
    -v /var/run/docker.sock:/var/run/docker.sock \
    containrrr/watchtower web api  # Only update "web" and "api" containers

Schedule Updates

# Use cron expression for update schedule
environment:
  - WATCHTOWER_SCHEDULE=0 0 4 * * *    # Every day at 4 AM

# Or use fixed interval
  - WATCHTOWER_POLL_INTERVAL=86400     # Every 24 hours

Notifications

# Slack notifications
environment:
  - WATCHTOWER_NOTIFICATIONS=slack
  - WATCHTOWER_NOTIFICATION_SLACK_HOOK_URL=https://hooks.slack.com/services/xxx/yyy/zzz

# Webhook notifications
  - WATCHTOWER_NOTIFICATIONS=shoutrrr
  - WATCHTOWER_NOTIFICATION_URL=generic+https://hooks.example.com/update

Private Registry Authentication

# Mount Docker config for registry credentials
docker run -d --name watchtower \
    -v /var/run/docker.sock:/var/run/docker.sock \
    -v $HOME/.docker/config.json:/config.json:ro \
    containrrr/watchtower

Run Once (Manual Updates)

# Check and update all containers once, then exit
docker run --rm -v /var/run/docker.sock:/var/run/docker.sock \
    containrrr/watchtower --run-once

Safety Considerations

• Do NOT use Watchtower with latest tags in production — pin specific version tags
• Use label-based filtering to control which containers are auto-updated
• Schedule updates during maintenance windows
• Enable notifications to know when updates occur
• Test updates in staging before enabling auto-update in production

Best Practices

• Use Watchtower for development and staging environments, not critical production systems
• Enable WATCHTOWER_CLEANUP to automatically remove old images
• Use --label-enable to explicitly opt-in containers for auto-update
• Schedule updates during low-traffic periods with cron expressions
• Always enable notifications to track what was updated and when
• For production, prefer CI/CD pipelines that test before deploying new images