Watchtower Docker Compose: Actualiza Contenedores Automáticamente 2026

Si gestionas contenedores Docker en tu homelab o servidor, sabes lo tedioso que es mantenerlos actualizados manualmente. Watchtower Docker Compose automatiza completamente este proceso, detectando nuevas versiones de imágenes y actualizando tus contenedores sin intervención manual. En esta guía completa aprenderás a configurarlo paso a paso.

¿Qué es Watchtower Docker Compose?

Watchtower es una solución containerizada que monitoriza tus contenedores Docker y actualiza automáticamente sus imágenes base cuando hay nuevas versiones disponibles. Con más de 24.4k estrellas en GitHub, se ha convertido en la herramienta esencial para automatizar actualizaciones en homelabs y entornos de desarrollo.

El proceso es simple pero potente: cuando detecta una nueva imagen, Watchtower descarga la actualización, detiene el contenedor existente de forma controlada y lo reinicia con la misma configuración original. Todo esto sin perder tus datos o configuraciones personalizadas.

Beneficios de Watchtower Docker Compose en tu Homelab

Automatización total: Olvídate de revisar manualmente cada contenedor
Seguridad mejorada: Recibe parches de seguridad automáticamente
Ahorro de tiempo: Reduce el mantenimiento de horas a minutos
Configuración flexible: Controla qué contenedores actualizar y cuándo
Notificaciones integradas: Recibe alertas por email, Slack, Teams o Gotify
Sin downtime prolongado: Actualizaciones rápidas con configuración preservada

Watchtower Docker Compose: Instalación Básica

La forma más práctica de desplegar esta herramienta es mediante Docker Compose. Crea un archivo docker-compose.yml con la siguiente configuración:

version: '3'

services:
  watchtower:
    image: containrrr/watchtower
    container_name: watchtower
    restart: unless-stopped
    volumes:
      - /var/run/docker.sock:/var/run/docker.sock
    environment:
      - TZ=Europe/Madrid
      - WATCHTOWER_CLEANUP=true
      - WATCHTOWER_INCLUDE_RESTARTING=true
      - WATCHTOWER_INCLUDE_STOPPED=false
      - WATCHTOWER_SCHEDULE=0 0 4 * * *

Esta configuración básica ejecuta actualizaciones automáticas cada día a las 4:00 AM, limpia imágenes antiguas y respeta tus zonas horarias. El acceso al socket de Docker (/var/run/docker.sock) es esencial para que el servicio pueda gestionar otros contenedores.

Watchtower Docker Compose: Configuración Avanzada

La configuración avanzada de Watchtower Docker Compose te permite personalizar completamente su comportamiento mediante variables de entorno. Aquí tienes un ejemplo completo con las funcionalidades más útiles:

version: '3'

services:
  watchtower:
    image: containrrr/watchtower
    container_name: watchtower
    restart: unless-stopped
    volumes:
      - /var/run/docker.sock:/var/run/docker.sock
    environment:
      # Zona horaria
      - TZ=Europe/Madrid

      # Programación con cron (todos los días a las 4 AM)
      - WATCHTOWER_SCHEDULE=0 0 4 * * *

      # Limpieza de imágenes antiguas
      - WATCHTOWER_CLEANUP=true

      # Incluir contenedores en reinicio
      - WATCHTOWER_INCLUDE_RESTARTING=true

      # No incluir contenedores detenidos
      - WATCHTOWER_INCLUDE_STOPPED=false

      # Modo de depuración
      - WATCHTOWER_DEBUG=false

      # Retraso antes de detener contenedor (segundos)
      - WATCHTOWER_TIMEOUT=10s

      # Notificaciones (veremos esto más adelante)
      - WATCHTOWER_NOTIFICATIONS=email
      - [email protected]
      - [email protected]
      - WATCHTOWER_NOTIFICATION_EMAIL_SERVER=smtp.gmail.com
      - WATCHTOWER_NOTIFICATION_EMAIL_SERVER_PORT=587
      - [email protected]
      - WATCHTOWER_NOTIFICATION_EMAIL_SERVER_PASSWORD=tu-password-app

Actualizar Contenedores Específicos con Labels

Si no quieres actualizar todos los contenedores automáticamente, puedes usar etiquetas (labels) para controlar exactamente qué servicios gestiona Watchtower. Esta es la configuración recomendada para entornos de producción.

Primero, configura Watchtower para monitorizar solo contenedores con etiquetas específicas:

version: '3'

services:
  watchtower:
    image: containrrr/watchtower
    container_name: watchtower
    restart: unless-stopped
    volumes:
      - /var/run/docker.sock:/var/run/docker.sock
    environment:
      - TZ=Europe/Madrid
      - WATCHTOWER_LABEL_ENABLE=true
      - WATCHTOWER_CLEANUP=true
      - WATCHTOWER_SCHEDULE=0 0 4 * * *

Luego, añade la etiqueta a los contenedores que quieres actualizar automáticamente:

version: '3'

services:
  nginx:
    image: nginx:latest
    container_name: nginx
    restart: unless-stopped
    labels:
      - "com.centurylinklabs.watchtower.enable=true"
    ports:
      - "80:80"

  portainer:
    image: portainer/portainer-ce:latest
    container_name: portainer
    restart: unless-stopped
    labels:
      - "com.centurylinklabs.watchtower.enable=true"
    ports:
      - "9000:9000"
    volumes:
      - /var/run/docker.sock:/var/run/docker.sock
      - portainer_data:/data

volumes:
  portainer_data:

Con esta configuración, solo los contenedores con la etiqueta com.centurylinklabs.watchtower.enable=true serán actualizados. El resto permanecerá intacto.

Programar Actualizaciones con Cron

La variable WATCHTOWER_SCHEDULE acepta expresiones cron de 6 campos para programar actualizaciones según tus necesidades:

Expresión Cron	Descripción
`0 0 4 * * *`	Cada día a las 4:00 AM
`0 0 /6 * *`	Cada 6 horas
`0 0 2 * * 0`	Domingos a las 2:00 AM
`0 30 3 1 * *`	Primer día del mes a las 3:30 AM
`0 0 5 * * 1-5`	Lunes a viernes a las 5:00 AM

El formato es: segundos minutos horas día-del-mes mes día-de-la-semana

Notificaciones en Watchtower Docker Compose

Una de las características más valiosas de Watchtower Docker Compose es su sistema de notificaciones. Puedes recibir alertas cada vez que se actualiza un contenedor, lo cual es crucial para monitorizar tu infraestructura de forma proactiva.

Notificaciones por Email

environment:
  - WATCHTOWER_NOTIFICATIONS=email
  - [email protected]
  - [email protected]
  - WATCHTOWER_NOTIFICATION_EMAIL_SERVER=smtp.gmail.com
  - WATCHTOWER_NOTIFICATION_EMAIL_SERVER_PORT=587
  - [email protected]
  - WATCHTOWER_NOTIFICATION_EMAIL_SERVER_PASSWORD=tu-password-app
  - WATCHTOWER_NOTIFICATION_EMAIL_SERVER_TLS_SKIP_VERIFY=false

Notificaciones por Slack

environment:
  - WATCHTOWER_NOTIFICATIONS=slack
  - WATCHTOWER_NOTIFICATION_SLACK_HOOK_URL=https://hooks.slack.com/services/XXX/YYY/ZZZ
  - WATCHTOWER_NOTIFICATION_SLACK_IDENTIFIER=watchtower-server
  - WATCHTOWER_NOTIFICATION_SLACK_CHANNEL=#actualizaciones

Notificaciones con Shoutrrr (Recomendado)

El método moderno y más flexible utiliza Shoutrrr, que soporta Discord, Telegram, Pushover, Gotify y muchos más:

environment:
  - WATCHTOWER_NOTIFICATION_URL=telegram://token@telegram?channels=channel-id discord://token@webhook-id gotify://gotify-server/token

Puedes configurar múltiples servicios de notificación separándolos con espacios.

Modo Monitor: Verificar Sin Actualizar

Si prefieres ser notificado de actualizaciones disponibles sin aplicarlas automáticamente, activa el modo monitor:

environment:
  - WATCHTOWER_MONITOR_ONLY=true
  - WATCHTOWER_NOTIFICATIONS=email
  - [email protected]
  - [email protected]

Con esta configuración, recibirás notificaciones cuando haya actualizaciones disponibles, pero Watchtower no las aplicará automáticamente. Útil para entornos donde prefieres control manual.

Watchtower Docker Compose con Registros Privados

Si usas registros privados (Docker Hub privado, GitLab Container Registry, Harbor, etc.), Watchtower Docker Compose soporta autenticación completa. Hay dos métodos principales:

Método 1: Credenciales en Variables de Entorno

environment:
  - REPO_USER=tu-usuario
  - REPO_PASS=tu-password

Método 2: Archivo config.json (Recomendado)

Primero, inicia sesión en tu registro desde el host:

docker login registry.tudominio.com

Luego, monta el archivo de configuración de Docker en el contenedor:

volumes:
  - /var/run/docker.sock:/var/run/docker.sock
  - /root/.docker/config.json:/config.json:ro

Este método es más seguro porque las credenciales están cifradas en el archivo config.json y no expuestas como variables de entorno.

Watchtower Docker Compose: Configuración de Producción

Aquí tienes una configuración completa de Watchtower Docker Compose que integra todas las mejores prácticas para entornos exigentes:

version: '3.8'

services:
  watchtower:
    image: containrrr/watchtower:latest
    container_name: watchtower
    restart: unless-stopped
    volumes:
      - /var/run/docker.sock:/var/run/docker.sock
      - /root/.docker/config.json:/config.json:ro
    environment:
      # Configuración básica
      - TZ=Europe/Madrid
      - WATCHTOWER_LABEL_ENABLE=true
      - WATCHTOWER_CLEANUP=true
      - WATCHTOWER_INCLUDE_RESTARTING=true
      - WATCHTOWER_ROLLING_RESTART=true

      # Programación: todos los días a las 3 AM
      - WATCHTOWER_SCHEDULE=0 0 3 * * *

      # Timeout personalizado
      - WATCHTOWER_TIMEOUT=30s

      # Notificaciones múltiples con Shoutrrr
      - WATCHTOWER_NOTIFICATION_URL=telegram://token@telegram?channels=123456 gotify://gotify.tudominio.com/APPTOKEN

      # Nivel de log
      - WATCHTOWER_NOTIFICATIONS_LEVEL=info

      # HTTP API para actualizaciones bajo demanda
      - WATCHTOWER_HTTP_API_UPDATE=true
      - WATCHTOWER_HTTP_API_TOKEN=tu-token-seguro-aqui
      - WATCHTOWER_HTTP_API_PERIODIC_POLLS=true
    ports:
      - "8080:8080"  # Solo si usas HTTP API
    labels:
      - "com.centurylinklabs.watchtower.enable=false"  # No actualizar a sí mismo

networks:
  default:
    name: homelab

Esta configuración incluye reinicio gradual de contenedores (ROLLING_RESTART), API HTTP para forzar actualizaciones bajo demanda, notificaciones múltiples, y se excluye a sí mismo de las actualizaciones automáticas.

API HTTP: Actualizar Contenedores Bajo Demanda

Con la API HTTP activada, puedes forzar actualizaciones manualmente sin esperar al cron programado:

curl -H "Authorization: Bearer tu-token-seguro-aqui" http://localhost:8080/v1/update

Esto es especialmente útil cuando despliegas una nueva versión crítica y necesitas actualizar inmediatamente sin esperar a la programación automática.

Watchtower Docker Compose: Casos de Uso Reales

1. Stack Multimedia Automatizado

Con Watchtower Docker Compose puedes mantener actualizados tus servicios multimedia (Jellyfin, Plex, Sonarr, Radarr) sin intervención manual:

version: '3.8'

services:
  jellyfin:
    image: jellyfin/jellyfin:latest
    container_name: jellyfin
    restart: unless-stopped
    labels:
      - "com.centurylinklabs.watchtower.enable=true"
    volumes:
      - ./config:/config
      - /media:/media
    ports:
      - "8096:8096"

  sonarr:
    image: linuxserver/sonarr:latest
    container_name: sonarr
    restart: unless-stopped
    labels:
      - "com.centurylinklabs.watchtower.enable=true"
    volumes:
      - ./sonarr:/config
      - /media/series:/tv
    ports:
      - "8989:8989"

  radarr:
    image: linuxserver/radarr:latest
    container_name: radarr
    restart: unless-stopped
    labels:
      - "com.centurylinklabs.watchtower.enable=true"
    volumes:
      - ./radarr:/config
      - /media/peliculas:/movies
    ports:
      - "7878:7878"

  watchtower:
    image: containrrr/watchtower:latest
    container_name: watchtower
    restart: unless-stopped
    volumes:
      - /var/run/docker.sock:/var/run/docker.sock
    environment:
      - TZ=Europe/Madrid
      - WATCHTOWER_LABEL_ENABLE=true
      - WATCHTOWER_CLEANUP=true
      - WATCHTOWER_SCHEDULE=0 0 4 * * *

2. Monitorización y Dashboards

Combínalo con herramientas de monitorización como Uptime Kuma, Grafana o Portainer para tener visibilidad completa de tu infraestructura.

3. Entorno de Desarrollo Siempre Actualizado

Ideal para desarrolladores que usan servicios como GitLab, Jenkins, SonarQube o bases de datos en contenedores.

Solución de Problemas Comunes

Watchtower Docker Compose No Actualiza Contenedores

Verifica que:

El socket Docker está correctamente montado: /var/run/docker.sock:/var/run/docker.sock
Si usas labels, están configurados correctamente en ambos lados
Las imágenes usan :latest o etiquetas específicas (no SHA256)
Revisa los logs: docker logs watchtower

Contenedores No Arrancan Después de Actualizar

Aumenta el timeout para dar más tiempo al contenedor anterior a detenerse correctamente:

environment:
  - WATCHTOWER_TIMEOUT=60s

No Recibo Notificaciones

Activa el modo debug para identificar el problema:

environment:
  - WATCHTOWER_DEBUG=true
  - WATCHTOWER_NOTIFICATIONS_LEVEL=debug

Luego revisa los logs detallados con docker logs watchtower.

Mejores Prácticas y Recomendaciones

Usa labels en lugar de actualizar todo: Te da control granular sobre qué servicios actualizar
Configura notificaciones: Sabrás inmediatamente cuando algo se actualiza o falla
Habilita WATCHTOWER_CLEANUP: Evita que el disco se llene con imágenes antiguas
Programa actualizaciones en horas de baja actividad: Minimiza el impacto en usuarios
Usa ROLLING_RESTART en producción: Evita que todos los servicios se detengan simultáneamente
No actualices bases de datos automáticamente: Excluye MySQL, PostgreSQL, MongoDB usando labels
Prueba primero en entorno de desarrollo: Usa el modo MONITOR_ONLY inicialmente
Implementa backups automáticos: Combina con soluciones como Duplicati o Restic

Monitorizar Watchtower con Prometheus y Grafana

Para entornos más avanzados, puedes integrar métricas de Watchtower con Prometheus y visualizarlas en Grafana. Esta configuración te permite rastrear actualizaciones, errores y rendimiento histórico.

Primero, habilita las métricas en tu configuración:

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:
      - TZ=Europe/Madrid
      - WATCHTOWER_CLEANUP=true
      - WATCHTOWER_HTTP_API_METRICS=true
      - WATCHTOWER_HTTP_API_TOKEN=token-seguro
    ports:
      - "8080:8080"

  prometheus:
    image: prom/prometheus:latest
    container_name: prometheus
    restart: unless-stopped
    volumes:
      - ./prometheus.yml:/etc/prometheus/prometheus.yml
      - prometheus_data:/prometheus
    ports:
      - "9090:9090"

  grafana:
    image: grafana/grafana:latest
    container_name: grafana
    restart: unless-stopped
    volumes:
      - grafana_data:/var/lib/grafana
    ports:
      - "3000:3000"
    environment:
      - GF_SECURITY_ADMIN_PASSWORD=admin

volumes:
  prometheus_data:
  grafana_data:

Configura Prometheus para scrapear las métricas de Watchtower creando prometheus.yml:

global:
  scrape_interval: 15s

scrape_configs:
  - job_name: 'watchtower'
    static_configs:
      - targets: ['watchtower:8080']
    metrics_path: '/v1/metrics'
    bearer_token: 'token-seguro'

Accede a Grafana en http://localhost:3000 (usuario: admin, contraseña: admin), añade Prometheus como datasource y crea dashboards personalizados para visualizar actualizaciones exitosas, fallos, tiempo de ejecución y más.

Integración con Sistemas CI/CD

Watchtower puede integrarse perfectamente en pipelines CI/CD para automatizar despliegues. Cuando tu pipeline construye y publica una nueva imagen Docker, Watchtower la detecta y actualiza automáticamente el contenedor en producción.

Por ejemplo, con GitLab CI/CD:

stages:
  - build
  - deploy

build:
  stage: build
  script:
    - docker build -t registry.tudominio.com/mi-app:latest .
    - docker push registry.tudominio.com/mi-app:latest

deploy:
  stage: deploy
  script:
    - curl -H "Authorization: Bearer token-seguro" http://servidor-produccion:8080/v1/update
  only:
    - main

Este workflow construye la imagen, la sube al registro y dispara una actualización inmediata en producción mediante la API HTTP de Watchtower. Es una solución elegante para homelabs que necesitan despliegues continuos sin la complejidad de Kubernetes.

Seguridad y Buenas Prácticas de Despliegue

El acceso al socket de Docker (/var/run/docker.sock) otorga privilegios de root al contenedor. Por seguridad, considera estas medidas:

Usar Docker Socket Proxy: Herramientas como tecnativa/docker-socket-proxy limitan los permisos del socket
Restringir por red: Coloca Watchtower en una red Docker aislada
Credenciales seguras: Usa Docker secrets o archivos montados en lugar de variables de entorno
Actualizar selectivamente: Nunca uses --run-all sin labels específicos
Logs centralizados: Integra con ELK Stack o Loki para auditoría

Ejemplo con Socket Proxy:

version: '3.8'

services:
  docker-socket-proxy:
    image: tecnativa/docker-socket-proxy
    container_name: docker-socket-proxy
    restart: unless-stopped
    volumes:
      - /var/run/docker.sock:/var/run/docker.sock:ro
    environment:
      - CONTAINERS=1
      - POST=0
    networks:
      - socket_proxy

  watchtower:
    image: containrrr/watchtower:latest
    container_name: watchtower
    restart: unless-stopped
    environment:
      - TZ=Europe/Madrid
      - DOCKER_HOST=tcp://docker-socket-proxy:2375
      - WATCHTOWER_CLEANUP=true
      - WATCHTOWER_LABEL_ENABLE=true
    networks:
      - socket_proxy

networks:
  socket_proxy:
    driver: bridge

Esta configuración reduce significativamente la superficie de ataque al limitar las operaciones que Watchtower puede realizar en el daemon de Docker.

Alternativas y Comparativas

Aunque Watchtower es excelente para homelabs, existen otras opciones según tu caso de uso:

Kubernetes con ArgoCD: Para entornos enterprise con orquestación compleja y GitOps
Portainer Business: Ofrece actualizaciones con interfaz gráfica y gestión de stacks
Diun: Solo notificaciones de actualizaciones disponibles, sin aplicarlas automáticamente
Ouroboros: Similar a Watchtower pero proyecto descontinuado con menos funcionalidades
Fleet by Rancher: GitOps para múltiples clusters Kubernetes

Para la mayoría de homelabs y entornos pequeños, Watchtower sigue siendo la opción más equilibrada entre funcionalidad, simplicidad y consumo de recursos. No requiere aprender Kubernetes ni configurar infraestructura compleja.

Preguntas Frecuentes (FAQ)

¿Es seguro usar Watchtower Docker Compose en producción?

Los desarrolladores de Watchtower Docker Compose recomiendan usarlo solo en homelabs y entornos de desarrollo. Para producción enterprise, considera soluciones como Kubernetes con políticas de actualización controladas. Sin embargo, con configuración cuidadosa (labels, modo monitor, notificaciones), puede usarse en pequeñas producciones.

¿Watchtower Docker Compose actualiza contenedores detenidos?

Por defecto Watchtower Docker Compose no actualiza contenedores detenidos. Debes habilitar WATCHTOWER_INCLUDE_STOPPED=true para incluir contenedores detenidos. También existe WATCHTOWER_REVIVE_STOPPED que inicia contenedores detenidos después de actualizarlos.

¿Cómo excluir contenedores específicos?

Usa la variable WATCHTOWER_LABEL_ENABLE=true y solo añade la etiqueta com.centurylinklabs.watchtower.enable=true a los contenedores que quieres actualizar. Los demás serán ignorados automáticamente.

¿Watchtower Docker Compose permite hacer rollback?

Watchtower Docker Compose no incluye rollback automático. La mejor práctica es mantener backups regulares de tus volúmenes y configuraciones. Si WATCHTOWER_CLEANUP=false, las imágenes antiguas permanecen y puedes revertir manualmente.

¿Qué consumo de recursos tiene Watchtower Docker Compose?

El consumo de recursos de Watchtower Docker Compose es extremadamente bajo. Usa menos de 20 MB de RAM en reposo y prácticamente 0% de CPU cuando no está actualizando. Durante actualizaciones, el consumo depende del tamaño de las imágenes que descarga.

Conclusión

Watchtower Docker Compose se ha consolidado como la herramienta imprescindible para automatizar actualizaciones de contenedores en homelabs y entornos de desarrollo. Con más de 24,000 estrellas en GitHub y una comunidad activa, ofrece el equilibrio perfecto entre automatización y control.

Desde la configuración básica hasta implementaciones avanzadas con notificaciones, API HTTP y gestión granular por labels, este tutorial te ha mostrado cómo aprovechar al máximo sus capacidades. Recuerda seguir las mejores prácticas: usa labels para control fino, configura notificaciones para visibilidad, programa actualizaciones en horarios apropiados y mantén backups regulares.

Aunque el proyecto fue archivado en diciembre de 2025, sigue siendo totalmente funcional y la imagen de Docker continuará disponible. Para la gran mayoría de usuarios de homelab, esta solución seguirá cubriendo todas las necesidades de automatización de actualizaciones durante años.

¿Listo para olvidarte de actualizar contenedores manualmente? Despliega tu configuración de Watchtower hoy mismo y recupera horas de mantenimiento cada mes. Tu homelab te lo agradecerá.