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

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"

Configuración

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

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 (TZ configurado)
  - --stop-timeout=30s      # Tiempo de gracia al parar contenedores

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)

Configuración de compatibilidad

Watchtower requiere especificar la versión de API de Docker para compatibilidad:

environment:
  - TZ=Europe/Madrid
  - DOCKER_API_VERSION=1.44

Esto asegura que Watchtower funcione correctamente con versiones modernas de Docker Engine.

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