How to Automate Docker Container Updates with Watchtower on Linux VPS

Maintaining container security in a production environment requires continuous vulnerability patching. Upstream maintainers regularly release new image tags resolving Common Vulnerabilities and Exposures (CVEs), patching memory leaks, and updating system dependencies. However, manually running docker pull and restarting containers across dozens of services on your Linux VPS is tedious and error-prone.

Watchtower is an open-source automation utility that monitors running Docker containers, queries remote container registries for newly pushed images, gracefully shuts down obsolete containers, and restarts them with their original run configurations and volumes intact. When configured properly, Watchtower provides hands-free security upgrades while preventing unintentional database breaking changes.

1. The Dangers of Unconstrained Auto-Updates

Before launching Watchtower with default parameters, understand the critical hazard of indiscriminate updates: breaking schema migrations and major software shifts. For instance, if an unpinned MariaDB or PostgreSQL container updates across major version boundaries (e.g., v15 to v16), the database will fail to start without running manual pg_upgrade routines, resulting in immediate downtime.

To safely operationalize Watchtower in production, follow three core rules:

1. Pin semantic version tags: Use image: redis:7.2-alpine instead of image: redis:latest. Watchtower will pull minor security patches (7.2.1, 7.2.2) without jumping to Redis 8.0.
2. Exclude critical stateful containers: Label databases and persistent storage engines to be ignored by Watchtower.
3. Configure automated alerting: Receive instant notifications via Discord, Slack, or email whenever an image update is applied.

2. Production Watchtower Docker Compose Configuration

Deploy Watchtower as an isolated service using Docker Compose. This production configuration runs scheduled checks at 04:00 AM daily, cleans up dangling images, and sends webhook notifications:

services:
  watchtower:
    image: containrrr/watchtower:latest
    restart: unless-stopped
    volumes:
      - /var/run/docker.sock:/var/run/docker.sock
    environment:
      # Schedule update check at 04:00 AM UTC daily (cron syntax)
      - WATCHTOWER_SCHEDULE=0 0 4 * * *
      # Automatically delete old, superseded images to save disk space
      - WATCHTOWER_CLEANUP=true
      # Require explicit opt-in label on target containers
      - WATCHTOWER_LABEL_ENABLE=true
      # Send webhooks upon update completion
      - WATCHTOWER_NOTIFICATIONS=shoutrrr
      - WATCHTOWER_NOTIFICATION_URL=discord://token@channel_id
      # Timeout for graceful container shutdown (seconds)
      - WATCHTOWER_TIMEOUT=30s
    deploy:
      resources:
        limits:
          memory: 128M

3. Opt-In vs Opt-Out Update Strategies

Watchtower supports two operational modes for selecting target containers:

Strategy A: Opt-In Mode (Recommended for Production)

By passing WATCHTOWER_LABEL_ENABLE=true, Watchtower strictly ignores all containers unless they explicitly include the label com.centurylinklabs.watchtower.enable=true. This is the safest approach because new containers never receive automated updates by mistake:

services:
  api:
    image: ghcr.io/organization/my-api:v1.2
    labels:
      - "com.centurylinklabs.watchtower.enable=true"

  database:
    image: mariadb:11.4
    # No label: Watchtower will completely ignore this database container!

Strategy B: Opt-Out Mode

If you prefer Watchtower to monitor all running containers by default, omit WATCHTOWER_LABEL_ENABLE and explicitly exclude stateful services using the disable label:

services:
  postgres_db:
    image: postgres:16-alpine
    labels:
      - "com.centurylinklabs.watchtower.enable=false"

4. Private Container Registry Authentication

If your production services pull private images from GitHub Container Registry (GHCR), GitLab Registry, or Docker Hub, Watchtower requires authentication credentials to poll for new image digests. Mount your Docker credentials config file into Watchtower:

services:
  watchtower:
    image: containrrr/watchtower:latest
    volumes:
      - /var/run/docker.sock:/var/run/docker.sock
      - /root/.docker/config.json:/config.json:ro
    environment:
      - DOCKER_CONFIG=/

Authenticate your VPS to your private registry beforehand using docker login ghcr.io to generate the required config.json credentials.

5. Running One-Off Dry Runs via CLI

Before leaving Watchtower on an automated cron schedule, execute a dry-run check to verify which containers would be updated without applying actual changes:

docker run --rm   -v /var/run/docker.sock:/var/run/docker.sock   containrrr/watchtower   --run-once   --monitor-only

The console output details each evaluated container, inspects remote registry digests, and confirms whether newer image layers exist.

Watchtower Production Hardening, Lifecycle Hooks & Discord Notifications

Taking Watchtower beyond basic auto-updates into an enterprise-grade automated patching engine requires configuring post-update notifications and container lifecycle hooks:

• Executing Pre-Update and Post-Update Scripts: Certain applications require flushing caches or putting services into maintenance mode prior to container replacement. Watchtower supports container lifecycle hooks via labels:

  services:
    app:
      image: ghcr.io/org/app:latest
      labels:
        - "com.centurylinklabs.watchtower.enable=true"
        - "com.centurylinklabs.watchtower.lifecycle.pre-update=/scripts/pre-update.sh"
        - "com.centurylinklabs.watchtower.lifecycle.post-update=/scripts/post-update.sh"

• Configuring Rich Discord & Slack Alerts: Watchtower utilizes the Shoutrrr notification library. To receive detailed status messages with timestamps, updated container tags, and failure logs, format your webhook URL:

  - WATCHTOWER_NOTIFICATIONS=shoutrrr
  - WATCHTOWER_NOTIFICATION_URL=discord://webhook_id:webhook_token@channel_id
  - WATCHTOWER_NOTIFICATION_TEMPLATE="{{range .}}{{.Time.Format "2006-01-02 15:04:05"}} - Container {{.Name}} updated from {{.OldImageID}} to {{.NewImageID}}{{println}}{{end}}"

• Preventing Simultaneous Service Restarts: In multi-tier stacks, restarting web workers and background queues simultaneously can drop active customer sessions. Configure WATCHTOWER_ROLLING_RESTART=true to upgrade containers sequentially rather than concurrently.
• Auditing Watchtower Logs: View recent update activity and verified registry digests directly via docker logs:

  docker logs --tail 50 -f watchtower

Common Watchtower Production Traps and How to Avoid Them

Even with careful configuration, automated container updates can encounter edge-case failures in complex environments. Keep these diagnostic rules in mind:

• Exhausting Registry API Rate Limits: Anonymous pulls against Docker Hub are strictly throttled to 100 requests per 6 hours. When Watchtower polls multiple containers every few minutes, you will quickly encounter 429 Too Many Requests HTTP errors. Always provide authenticated credentials via /root/.docker/config.json or configure longer polling intervals (e.g., once daily at night).
• Handling Failed Container Health Checks: If an updated container fails its internal health check, Watchtower will terminate the unhealthy instance. By configuring WATCHTOWER_ROLLBACK_ON_FAIL=true, Watchtower can automatically reinstate the prior working image layer, ensuring zero extended downtime.
• Managing Linked Dependencies: If two containers depend on an internal socket or shared IPC, restarting one can crash the dependent service. Use Docker Compose depends_on and configure Watchtower to monitor both services as a coordinated group.