Watchtower Automatic Docker Updates

Watchtower automatically updates Docker contenedores with new imágenes, eliminating manual update procedures and ensuring your applications always run the latest versions. Esta guía completa cubre installation, scheduling, notifications, cleanup policies, label filtering, and operational considerations. Proper automation of contenedor updates reduces maintenance burden while improving security posture through timely vulnerability patching.

Tabla de Contenidos

• Comprendiendo Watchtower
• Installing Watchtower
• Basic Configuración
• Scheduling Updates
• Actualiza Notifications
• Filtering and Selection
• Actualiza Strategies
• Monitoreo Mode
• Cleanup and Mantenimiento
• Conclusión

Comprendiendo Watchtower

Watchtower monitors running Docker contenedores and their imágenes, automatically pulling new imágenes and restarting contenedores when updates are detected. This ensures your containerized applications always run current versions without manual intervention.

Key features:

• Automatic imagen update detection
• Scheduled update execution
• Selective contenedor targeting
• Multiple notification channels
• Cleanup of old imágenes
• Pre-update checks and dry-runs
• Include/exclude filtering
• Rollback on failure (optional)

Actualiza workflow:

1. Watchtower polls imagen registro for newer versions
2. Compares current running version with latest available
3. Pulls new imagen if update found
4. Stops running contenedor
5. Starts new contenedor with updated imagen
6. Optionally cleans up old imágenes
7. Sends notification about update

Installing Watchtower

Despliega Watchtower as a contenedor servicio.

Basic Watchtower deployment:

# Ejecuta Watchtower
docker run -d \
  --name watchtower \
  --restart always \
  -v /var/run/docker.sock:/var/run/docker.sock \
  containrrr/watchtower

# Verifica running
docker ps | grep watchtower

# Check logs
docker logs watchtower

Docker Compose deployment:

cat > docker-compose.yml <<'EOF'
version: '3.9'

servicios:
  watchtower:
    imagen: containrrr/watchtower:latest
    container_name: watchtower
    restart: always
    volúmenes:
      - /var/run/docker.sock:/var/run/docker.sock
    environment:
      WATCHTOWER_SCHEDULE: "0 0 * * * *"
      WATCHTOWER_CLEANUP: "true"
      WATCHTOWER_REMOVE_VOLUMES: "false"
      WATCHTOWER_INCLUDE_RESTARTING: "true"

  app:
    imagen: nginx:latest
    container_name: web
    restart: always
    puertos:
      - "80:80"

EOF

docker-compose up -d

Watchtower with Docker Swarm:

# Despliega as Swarm servicio
docker servicio create \
  --name watchtower \
  --mode global \
  --restart-condition any \
  --mount type=bind,source=/var/run/docker.sock,target=/var/run/docker.sock \
  -e WATCHTOWER_SCHEDULE="0 0 * * * *" \
  -e WATCHTOWER_CLEANUP=true \
  containrrr/watchtower

# Verifica deployment
docker servicio ls
docker servicio ps watchtower

Basic Configuración

Configura Watchtower behavior and update policies.

Environment variables configuration:

docker run -d \
  --name watchtower \
  -v /var/run/docker.sock:/var/run/docker.sock \
  -e WATCHTOWER_SCHEDULE="0 0 * * * *" \
  -e WATCHTOWER_CLEANUP=true \
  -e WATCHTOWER_REMOVE_VOLUMES=false \
  -e WATCHTOWER_INCLUDE_STOPPED=false \
  -e WATCHTOWER_INCLUDE_RESTARTING=false \
  -e WATCHTOWER_TIMEOUT=10 \
  -e DEBUG=true \
  containrrr/watchtower

Common configuration options:

• WATCHTOWER_SCHEDULE: Cron schedule for checks (default: 86400s/24h)
• WATCHTOWER_CLEANUP: Remueve old imágenes after update
• WATCHTOWER_REMOVE_VOLUMES: Elimina volúmenes on contenedor removal
• WATCHTOWER_INCLUDE_STOPPED: Actualiza stopped contenedores
• WATCHTOWER_INCLUDE_RESTARTING: Actualiza restarting contenedores
• WATCHTOWER_TIMEOUT: Shutdown timeout in seconds
• DEBUG: Habilita debug logging

Target specific contenedores:

# Actualiza specific contenedores (others ignored)
docker run -d \
  --name watchtower \
  -v /var/run/docker.sock:/var/run/docker.sock \
  containrrr/watchtower \
  web app database

# Actualiza only contenedores with label
docker run -d \
  --name watchtower \
  -v /var/run/docker.sock:/var/run/docker.sock \
  -e WATCHTOWER_LABEL_ENABLE=true \
  containrrr/watchtower

# Label contenedores for auto-update
docker run -d \
  --name myapp \
  --label com.centurylinklabs.watchtower=true \
  myapp:latest

Scheduling Updates

Configura when Watchtower performs updates.

Cron schedule expressions:

# Common schedules
# Every day at midnight
WATCHTOWER_SCHEDULE="0 0 * * * *"

# Every Sunday at 2 AM
WATCHTOWER_SCHEDULE="0 2 0 * * 0"

# Every 6 hours
WATCHTOWER_SCHEDULE="0 */6 * * * *"

# Every business day at 3 AM
WATCHTOWER_SCHEDULE="0 3 * * 1-5"

# Every 30 minutes
WATCHTOWER_SCHEDULE="0 */30 * * * *"

docker run -d \
  --name watchtower \
  -v /var/run/docker.sock:/var/run/docker.sock \
  -e "WATCHTOWER_SCHEDULE=0 0 * * * *" \
  containrrr/watchtower

Actualiza timing strategies:

# Low-traffic windows (3 AM daily)
cat > docker-compose.yml <<'EOF'
servicios:
  watchtower:
    imagen: containrrr/watchtower:latest
    environment:
      # Actualiza during maintenance window
      WATCHTOWER_SCHEDULE: "0 3 * * *"
      # Give contenedores 30 seconds to gracefully shutdown
      WATCHTOWER_TIMEOUT: 30
      # Stagger update checks
      WATCHTOWER_CHECK_INTERVAL: 3600
EOF

Dry-run before actual update:

# Dry-run mode (verifica what would update, don't apply)
docker run -d \
  --name watchtower-dryrun \
  -v /var/run/docker.sock:/var/run/docker.sock \
  -e WATCHTOWER_DRY_RUN=true \
  -e WATCHTOWER_RUN_ONCE=true \
  containrrr/watchtower

# Check logs to see what would be updated
docker logs watchtower-dryrun

# Then enable for real updates
docker run -d \
  --name watchtower \
  -v /var/run/docker.sock:/var/run/docker.sock \
  -e WATCHTOWER_DRY_RUN=false \
  containrrr/watchtower

Actualiza Notifications

Send notifications when Watchtower performs updates.

Email notifications:

docker run -d \
  --name watchtower \
  -v /var/run/docker.sock:/var/run/docker.sock \
  -e [email protected] \
  -e [email protected] \
  -e WATCHTOWER_NOTIFICATION_EMAIL_SERVER=smtp.gmail.com \
  -e WATCHTOWER_NOTIFICATION_EMAIL_SERVER_PORT=587 \
  -e [email protected] \
  -e WATCHTOWER_NOTIFICATION_EMAIL_SERVER_PASSWORD=your-app-password \
  containrrr/watchtower

Slack notifications:

# Crea Slack webhook: https://api.slack.com/apps

docker run -d \
  --name watchtower \
  -v /var/run/docker.sock:/var/run/docker.sock \
  -e WATCHTOWER_NOTIFICATIONS=slack \
  -e WATCHTOWER_NOTIFICATION_SLACK_HOOK_URL=https://hooks.slack.com/servicios/YOUR/WEBHOOK/URL \
  -e WATCHTOWER_NOTIFICATION_SLACK_IDENTIFIER=watchtower \
  containrrr/watchtower

Multiple notification channels:

cat > docker-compose.yml <<'EOF'
version: '3.9'

servicios:
  watchtower:
    imagen: containrrr/watchtower:latest
    volúmenes:
      - /var/run/docker.sock:/var/run/docker.sock
    environment:
      # Email
      WATCHTOWER_NOTIFICATIONS: email
      WATCHTOWER_NOTIFICATION_EMAIL_FROM: [email protected]
      WATCHTOWER_NOTIFICATION_EMAIL_TO: [email protected]
      WATCHTOWER_NOTIFICATION_EMAIL_SERVER: smtp.gmail.com
      WATCHTOWER_NOTIFICATION_EMAIL_SERVER_PORT: 587
      WATCHTOWER_NOTIFICATION_EMAIL_SERVER_USER: ${GMAIL_USER}
      WATCHTOWER_NOTIFICATION_EMAIL_SERVER_PASSWORD: ${GMAIL_PASSWORD}
      
      # Slack
      WATCHTOWER_NOTIFICATION_SLACK_HOOK_URL: ${SLACK_WEBHOOK}
      
      # Schedule
      WATCHTOWER_SCHEDULE: "0 0 * * * *"
      WATCHTOWER_CLEANUP: "true"

EOF

docker-compose up -d

Filtering and Selection

Selectively update contenedores with labels and patterns.

Label-based filtering:

# Habilita label-based filtering
docker run -d \
  --name watchtower \
  -v /var/run/docker.sock:/var/run/docker.sock \
  -e WATCHTOWER_LABEL_ENABLE=true \
  containrrr/watchtower

# Despliega contenedores with update labels
docker run -d \
  --name auto-update-app \
  --label com.centurylinklabs.watchtower=true \
  app:latest

# This contenedor will be updated
docker run -d \
  --name manual-app \
  --label com.centurylinklabs.watchtower=false \
  app:latest

# This contenedor won't be updated

Imagen-based filtering:

# Actualiza only specific imagen pattern
docker run -d \
  --name watchtower \
  -v /var/run/docker.sock:/var/run/docker.sock \
  containrrr/watchtower \
  myregistry.com/myapp

# Actualiza only this imagen, ignore others

Named contenedor targeting:

# Actualiza specific contenedores by name
docker run -d \
  --name watchtower \
  -v /var/run/docker.sock:/var/run/docker.sock \
  containrrr/watchtower \
  web app database

# Updates only: web, app, database
# Ignores: cache, backup, etc.

Actualiza Strategies

Implement different update strategies based on requirements.

Rolling updates:

# Docker Compose with rolling update strategy
cat > docker-compose.yml <<'EOF'
version: '3.9'

servicios:
  watchtower:
    imagen: containrrr/watchtower:latest
    volúmenes:
      - /var/run/docker.sock:/var/run/docker.sock
    environment:
      WATCHTOWER_SCHEDULE: "0 0 * * * *"
      WATCHTOWER_CLEANUP: "true"
      WATCHTOWER_ROLLING_RESTART: "true"

  app:
    imagen: myapp:latest
    restart: always
    deploy:
      réplicas: 3
      update_config:
        parallelism: 1
        delay: 10s

EOF

Actualiza with health checks:

# Actualiza only if health verifica passes
docker run -d \
  --name app \
  --health-cmd="curl -f http://localhost/ || exit 1" \
  --health-interval=10s \
  --health-timeout=5s \
  --health-retries=3 \
  app:latest

# Watchtower respects health status
docker run -d \
  --name watchtower \
  -v /var/run/docker.sock:/var/run/docker.sock \
  -e WATCHTOWER_SCHEDULE="0 0 * * * *" \
  containrrr/watchtower

Scheduled maintenance windows:

# Actualiza only during specific windows
cat > /usr/local/bin/watchtower-update.sh <<'EOF'
#!/bin/bash

# Check if in maintenance window (2-4 AM)
HOUR=$(date +%H)
if [ "$HOUR" -ge 2 ] && [ "$HOUR" -lt 4 ]; then
    docker exec watchtower watchtower --run-once
else
    echo "Outside maintenance window"
fi
EOF

chmod +x /usr/local/bin/watchtower-update.sh

# Schedule
0 * * * * /usr/local/bin/watchtower-update.sh

Monitoreo Mode

Use Watchtower in monitor-only mode without automatic updates.

Monitorea-only configuration:

# Ejecuta Watchtower without updating (monitor only)
docker run -d \
  --name watchtower-monitor \
  -v /var/run/docker.sock:/var/run/docker.sock \
  -e WATCHTOWER_DRY_RUN=true \
  -e [email protected] \
  -e [email protected] \
  -e WATCHTOWER_NOTIFICATION_EMAIL_SERVER=smtp.gmail.com \
  -e WATCHTOWER_NOTIFICATIONS=email \
  containrrr/watchtower

# Watchtower alerts about available updates without applying them

Report available updates:

# Get list of available updates
docker run --rm \
  -v /var/run/docker.sock:/var/run/docker.sock \
  containrrr/watchtower \
  --dry-run

# Output shows what would be updated without applying changes

Cleanup and Mantenimiento

Manage old imágenes and maintain system health.

Habilita automatic cleanup:

docker run -d \
  --name watchtower \
  -v /var/run/docker.sock:/var/run/docker.sock \
  -e WATCHTOWER_CLEANUP=true \
  -e WATCHTOWER_REMOVE_VOLUMES=false \
  -e WATCHTOWER_CLEANUP_PERIOD=86400 \
  containrrr/watchtower

# WATCHTOWER_CLEANUP: Remueve unused imágenes
# WATCHTOWER_REMOVE_VOLUMES: Remueve volúmenes on update
# WATCHTOWER_CLEANUP_PERIOD: Cleanup interval in seconds (default: 86400/24h)

Monitorea Watchtower health:

# Check Watchtower logs
docker logs watchtower | tail -50

# Monitorea disk usage
docker system df

# Clean up manually if needed
docker imagen prune -a --force

# Check Watchtower contenedor status
docker inspect watchtower | grep -A 10 State

Soluciona failed updates:

# Habilita debug logging
docker run -d \
  --name watchtower \
  -v /var/run/docker.sock:/var/run/docker.sock \
  -e DEBUG=true \
  containrrr/watchtower

# Check detailed logs
docker logs watchtower --follow

# Identify failed contenedores
docker ps -a --filter status=exited

# Check what Watchtower is monitoring
docker run --rm \
  -v /var/run/docker.sock:/var/run/docker.sock \
  containrrr/watchtower \
  --list-monitored

Conclusión

Watchtower automates the critical tarea of keeping containerized applications updated with the latest imágenes, reducing operational overhead while improving security through timely vulnerability patching. By configuring appropriate schedules, filtering rules, and notifications, you create a self-updating infrastructure that requires minimal manual intervention. Inicia with basic nightly updates for non-critical contenedores, progress to selective updates using labels for production systems, and eventually integrate with monitoring and notification systems for complete visibility. Whether running a few contenedores or managing complex microservices deployments, Watchtower simplifies the update management burden. Combine automatic updates with proper health checks, monitoring, and rollback capabilities for a production-grade automated update solution.