$docker.recipes

Watchtower Container Updates

beginner

Watchtower automatic container base image updates.

[i]Overview

Watchtower is an automated Docker container update service that continuously monitors running containers for base image updates and performs rolling updates without manual intervention. Originally developed by CenturyLinkLabs and now maintained by Containrrr, Watchtower addresses the critical DevOps challenge of keeping containerized applications current with security patches and feature updates while minimizing downtime. It works by periodically polling Docker registries for newer image versions, comparing them against running containers, and automatically pulling new images and recreating containers when updates are detected. This Watchtower configuration establishes an automated container lifecycle management system that operates independently in the background, scanning all running containers every 24 hours by default. The setup includes automatic cleanup of old images to prevent disk space bloat, timezone synchronization for accurate scheduling, and selective monitoring that focuses only on active containers while ignoring stopped ones. Watchtower connects directly to the Docker daemon through the Docker socket, giving it the necessary permissions to manage container lifecycles across the entire host system. This automation stack is particularly valuable for homelab enthusiasts, small development teams, and organizations running containerized services without dedicated DevOps personnel. Unlike manual update processes that require scheduling maintenance windows and coordinating deployments, Watchtower enables a "set it and forget it" approach to container maintenance. The configuration provides intelligent defaults that balance update frequency with system stability, making it ideal for environments where containers need to stay current but don't require enterprise-grade deployment orchestration.

[*]Key Features

  • [+]Automatic base image monitoring and container recreation when updates are detected
  • [+]Configurable polling intervals from minutes to days for update frequency control
  • [+]Selective container management using Docker labels to include or exclude specific containers
  • [+]Automatic cleanup of outdated Docker images to prevent disk space accumulation
  • [+]Rolling restart capability that updates containers one at a time to maintain service availability
  • [+]Private Docker registry support with authentication for enterprise image repositories
  • [+]Lifecycle hooks for pre-update and post-update custom scripting and notifications
  • [+]Multiple notification channels including email, Slack, Teams, and webhook integrations

[#]Common Use Cases

  • [1]Homelab servers running media centers, network attached storage, and home automation containers
  • [2]Development and staging environments where teams need latest features without manual intervention
  • [3]Small business applications requiring automatic security updates for compliance requirements
  • [4]IoT and edge computing deployments where manual updates are impractical or impossible
  • [5]Personal VPS hosting multiple services that need to stay current with minimal maintenance overhead
  • [6]Educational environments where students deploy containers that should automatically receive updates
  • [7]Prototype and demo environments where showcasing latest features requires current container versions

[!]Prerequisites

  • [!]Docker Engine 19.03+ with Docker Compose v2.0+ for container orchestration support
  • [!]Minimum 64MB RAM available for Watchtower container operation and image processing
  • [!]Docker socket access permissions for container lifecycle management and image operations
  • [!]Network connectivity to Docker registries (Docker Hub, private registries) for image polling
  • [!]Sufficient disk space for downloading new images during update cycles (varies by container size)
  • [!]Understanding of Docker labels and container naming for selective update configuration
[!]

WARNING: For development & testing. Review security settings, change default credentials, and test thoroughly before production use. See Terms

[$]docker-compose.yml

[docker-compose.yml]
1services: 
2  watchtower: 
3    image: containrrr/watchtower:latest
4    container_name: watchtower
5    environment: 
6      - TZ=${TZ}
7      - WATCHTOWER_CLEANUP=true
8      - WATCHTOWER_POLL_INTERVAL=86400
9      - WATCHTOWER_INCLUDE_STOPPED=false
10      - WATCHTOWER_REVIVE_STOPPED=false
11    volumes: 
12      - /var/run/docker.sock:/var/run/docker.sock
13    restart: unless-stopped
14    networks: 
15      - watchtower-network
16
17volumes: 
18  watchtower_data: 
19
20networks: 
21  watchtower-network: 
22    driver: bridge

[$].env Template

[.env]
1# Watchtower
2TZ=UTC

[i]Usage Notes

  1. [1]Runs automatically
  2. [2]Default: checks every 24 hours
  3. [3]Use labels to include/exclude containers
  4. [4]Notifications via email, Slack, etc.
  5. [5]Monitors only running containers

[>]Quick Start

[terminal]
1# 1. Create the compose file
2cat > docker-compose.yml << 'EOF'
3services:
4  watchtower:
5    image: containrrr/watchtower:latest
6    container_name: watchtower
7    environment:
8      - TZ=${TZ}
9      - WATCHTOWER_CLEANUP=true
10      - WATCHTOWER_POLL_INTERVAL=86400
11      - WATCHTOWER_INCLUDE_STOPPED=false
12      - WATCHTOWER_REVIVE_STOPPED=false
13    volumes:
14      - /var/run/docker.sock:/var/run/docker.sock
15    restart: unless-stopped
16    networks:
17      - watchtower-network
18
19volumes:
20  watchtower_data:
21
22networks:
23  watchtower-network:
24    driver: bridge
25EOF
26
27# 2. Create the .env file
28cat > .env << 'EOF'
29# Watchtower
30TZ=UTC
31EOF
32
33# 3. Start the services
34docker compose up -d
35
36# 4. View logs
37docker compose logs -f

[>]One-Liner

Run this command to download and set up the recipe in one step:

[terminal]
1curl -fsSL https://docker.recipes/api/recipes/watchtower-updates/run | bash

[?]Troubleshooting

  • [!]Permission denied accessing Docker socket: Add watchtower container to docker group or verify socket permissions are 666
  • [!]Watchtower not detecting image updates: Check registry connectivity and verify image tags aren't using 'latest' ambiguously
  • [!]Container recreation fails with dependency errors: Review container start order and add depends_on declarations to dependent services
  • [!]High disk usage from old images: Verify WATCHTOWER_CLEANUP=true is set and consider adding WATCHTOWER_INCLUDE_RESTARTING=true
  • [!]Containers not updating despite new images available: Check container labels for com.centurylinklabs.watchtower.enable=false exclusions
  • [!]Watchtower consuming excessive CPU during scans: Increase WATCHTOWER_POLL_INTERVAL to reduce scanning frequency and system load

Community Notes

Loading...
Loading notes...

## Download Recipe Kit

Get all files in a ready-to-deploy package

Includes docker-compose.yml, .env template, README, and license

## Components

watchtower

## Tags

#watchtower#docker#updates#automation#containers

## Category

DevOps & CI/CD

## Related