Skip to main content

Watchtower

image.png

Watchtower es un contenedor que se ejecuta en segundo plano y se encarga de vigilar tus contenedores Docker y actualizarlos automáticamente cuando detecta que hay una nueva imagen disponible en el registry (Docker Hub, GitHub Container Registry, etc.). En otras palabras: es un “autoupdater” para Docker.

Watchtower actúa sobre todo el host (todos los stacks) compartiendo el daemon Docker. Para que actualice contenedores  añade la label com.centurylinklabs.watchtower.enable=true en esos servicios dentro de sus propios docker-compose.yaml.

    labels:
      - "com.centurylinklabs.watchtower.enable=true"

  • Watchtower comprueba periódicamente las imágenes de los contenedores que tengas corriendo.

  • Si encuentra una versión más reciente, la descarga.

  • Para cada contenedor afectado:

    • Lo detiene,

    • Lo recrea usando la nueva imagen,

    • Lo arranca de nuevo con las mismas opciones (puertos, volúmenes, variables de entorno, etc.) que tenía antes.

Enlaces

Características

  • Actualiza solo contenedores etiquetados (flag --label-enable)
  • Limpieza de imágenes antiguas (flag --cleanup)
  • Programación vía cron con flag --schedule
  • Tiempo de gracia en parada (--stop-timeout)
  • Notificaciones (Shoutrrr: Telegram, Slack, Email, etc.)

Despliegue

git clone https://git.ictiberia.com/groales/watchtower
cd watchtower
docker compose up -d

Configuración

El docker-compose.yaml utiliza flags en lugar de variables de entorno para mayor claridad:

services:
  watchtower:
    image: containrrr/watchtower
    container_name: watchtower
    restart: unless-stopped
    environment:
      - TZ=Europe/Madrid
      - DOCKER_API_VERSION=1.44 # Asegura compatibilidad
    volumes:
      - /var/run/docker.sock:/var/run/docker.sock:ro
    command:
      - --label-enable          # Solo contenedores con label enable=true
      - --cleanup               # Elimina imágenes antiguas tras actualizar
      - --schedule=0 30 3 * * * # Ejecuta cada día a las 03:30
      - --stop-timeout=30s      # Tiempo de gracia al parar contenedores

Etiquetado de servicios

Para que un servicio se auto-actualice, añade la label:

labels:
  - "com.centurylinklabs.watchtower.enable=true"

Para excluir explícitamente:

labels:
  - "com.centurylinklabs.watchtower.enable=false"

Buenas prácticas

  • Etiqueta solo servicios que quieras actualizar
  • Usa horarios de baja actividad (madrugada)
  • Revisa logs tras cambios de versiones críticas
  • Mantén backups si actualizas servicios con datos persistentes
  • Excluye servicios que gestionas manualmente (enable=false)

Troubleshooting

docker logs watchtower --tail=200

Forzar actualización

1. Contenedor temporal (one-shot)

Lanzar un contenedor Watchtower independiente, con los mismos parámetros, pero añadiendo --run-once:

docker run --rm \
  -v /var/run/docker.sock:/var/run/docker.sock \
  containrrr/watchtower \
  --run-once --label-enable --cleanup

2. Lanzar un escaneo manual en el contenedor existente

docker exec -it watchtower /watchtower --run-once --cleanup

Así usas el mismo contenedor que ya tienes corriendo.

Back to top