How to Configure Automated Docker Container Updates: WatchTower vs Diun

You can configure automated Docker container updates by deploying WatchTower as a sidecar container for fully automatic updates, or Diun for notification-driven updates, both requiring secure access to the Docker socket at /var/run/docker.sock.

Self-hosting services with Docker requires regular image updates to patch security vulnerabilities and access new features. Instead of manually pulling images and recreating containers, the mikeroyal/Self-Hosting-Guide repository documents production-ready tools that handle this automatically. This guide explains how to implement automated Docker container updates using WatchTower, Diun, and Autoheal based on the configurations found in the repository's README.md.

WatchTower: Fully Automatic Updates

WatchTower monitors running containers and automatically pulls newer images when they become available, then recreates the affected containers with identical configuration. According to the Self-Hosting-Guide README.md at line 84, this is the most hands-off approach for maintaining current images.

Configuration Options

WatchTower behavior is controlled through environment variables:

• WATCHTOWER_LABEL_ENABLE: Set to true to only update containers carrying the specific label com.centurylinklabs.watchtower.enable=true
• WATCHTOWER_CLEANUP: Set to true to remove old images after successful updates, preventing disk space accumulation
• WATCHTOWER_POLL_INTERVAL: Define check frequency in seconds (default is 300 seconds/5 minutes)

Docker Compose Implementation

Create a docker-compose.yml file that mounts the Docker socket and configures the environment:

version: "3.8"
services:
  watchtower:
    image: containrrr/watchtower:latest
    container_name: watchtower
    restart: unless-stopped
    volumes:
      - /var/run/docker.sock:/var/run/docker.sock
    environment:
      WATCHTOWER_LABEL_ENABLE: "true"
      WATCHTOWER_CLEANUP: "true"
      WATCHTOWER_POLL_INTERVAL: "21600"
    deploy:
      resources:
        limits:
          memory: 200M

To opt-in specific services for automatic updates, add the label to their configuration:

services:
  myapp:
    image: myorg/myapp:latest
    labels:
      - "com.centurylinklabs.watchtower.enable=true"

Diun: Notification-Driven Updates

Diun (Docker Image Update Notifier) watches configured registries and sends alerts when newer images appear without automatically applying them. This approach, documented in README.md at line 82, is ideal for critical services requiring maintenance windows or manual approval before updates.

Creating the Diun Configuration

Create a diun.yml file specifying images to monitor and notification endpoints:

watch:
  - name: "myorg/myapp"
    tags:
      - "latest"
    includeTags: true
  - name: "nginx"
    tags:
      - "stable"
    includeTags: true

notify:
  slack:
    webhook: "https://hooks.slack.com/services/XXXXX/XXXXX/XXXXX"
    channel: "#updates"
    username: "Diun"
    icon_emoji: ":whale:"

Docker Compose Implementation

Deploy Diun with the configuration file mounted as a read-only volume:

version: "3.8"
services:
  diun:
    image: crazymax/diun:latest
    container_name: diun
    restart: unless-stopped
    volumes:
      - /var/run/docker.sock:/var/run/docker.sock
      - ./diun.yml:/diun.yml:ro
    command: ["run", "--config", "/diun.yml"]

When Diun detects updates, it posts notifications like "Update available – myorg/myapp:latest → myorg/myapp:1.4.2", allowing you to manually run docker pull and docker compose up -d at your convenience.

Autoheal: Automated Container Restart

While not an update tool, Autoheal complements WatchTower and Diun by monitoring container health checks and automatically restarting unhealthy containers. As noted in README.md at line 78, this ensures services remain available if updates cause temporary issues or if containers become unresponsive.

Deploy Autoheal with:

version: "3.8"
services:
  autoheal:
    image: willfarrell/autoheal:latest
    container_name: autoheal
    restart: unless-stopped
    volumes:
      - /var/run/docker.sock:/var/run/docker.sock
    environment:
      AUTOHEAL_INTERVAL: 60

Security Considerations

Both WatchTower and Diun require mounting /var/run/docker.sock to control other containers, which grants significant privileges over the host system. Run these update containers with the least privilege necessary, keep the host's Docker daemon patched, and consider using Diun's notification-only mode for production-critical services to prevent automatic updates from introducing breaking changes.

Summary

• WatchTower provides fully automatic updates by polling registries and recreating containers, configured via environment variables like WATCHTOWER_LABEL_ENABLE and WATCHTOWER_CLEANUP
• Diun offers notification-driven updates through diun.yml configuration, supporting Slack, Discord, email, and other channels without automatic deployment
• Autoheal automatically restarts unhealthy containers but does not update images, serving as a reliability companion to update tools
• All tools require Docker socket access at /var/run/docker.sock, necessitating careful security practices and least-privilege deployment
• The mikeroyal/Self-Hosting-Guide documents these tools at specific lines in README.md: WatchTower (line 84), Diun (line 82), and Autoheal (line 78)

Frequently Asked Questions

What is the difference between WatchTower and Diun for automated Docker container updates?

WatchTower automatically pulls new images and recreates containers without manual intervention, while Diun only sends notifications when updates are available, allowing you to control when updates are applied. WatchTower is best for homelab environments where automatic updates are acceptable, whereas Diun suits production systems requiring change management approval.

How do I prevent WatchTower from updating specific containers?

Set WATCHTOWER_LABEL_ENABLE: "true" in the WatchTower environment variables and only add the label com.centurylinklabs.watchtower.enable=true to containers you want automatically updated. Containers without this label will be ignored by WatchTower, giving you granular control over which services receive automatic updates.

Can I use WatchTower and Diun together for automated Docker container updates?

Yes, a common pattern is running WatchTower for most services where you accept automatic updates, while using Diun for critical services that require notification before updating. This hybrid approach provides automation for stable applications while maintaining manual oversight for sensitive production workloads.

Why does Autoheal require access to the Docker socket?

Autoheal mounts /var/run/docker.sock to monitor container health status and execute restart commands on containers that become unhealthy. While it does not update images, it requires socket access to interact with the Docker daemon and manage container lifecycle states, similar to WatchTower and Diun.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}