Aller au contenu
0 Votes

Watchtower

Modifié par john le 2026/09/20 18:43

Watchtower

Mise à jour automatique des images Docker des conteneurs de la machine.

Rôle

Watchtower surveille les registres des images utilisées par les conteneurs en cours d'exécution, télécharge les nouvelles versions et recrée les conteneurs avec la configuration présente dans Docker au moment de la mise à jour (variables, volumes, réseaux, labels). Il ne lit pas les fichiers Compose et ne connaît pas les stacks Portainer : une image épinglée sur un tag fixe n'est jamais mise à jour, seuls les tags mouvants (latest, stable) le sont.

Fork utilisé

Le projet d'origine containrrr/watchtower est archivé depuis décembre 2025. L'image utilisée est le fork maintenu nickfedor/watchtower, qui conserve les variables WATCHTOWER_* et l'espace de noms de labels com.centurylinklabs.watchtower.*.

Documentation : watchtower.nickfedor.com

Stack

services:
 watchtower:
   image: nickfedor/watchtower:latest
   container_name: watchtower
   restart: unless-stopped
   environment:
      - TZ=<FUSEAU_HORAIRE>
      - WATCHTOWER_SCHEDULE=0 0 5 * * *
      - WATCHTOWER_CLEANUP=true
   volumes:
      - /var/run/docker.sock:/var/run/docker.sock
  • WATCHTOWER_SCHEDULE utilise un cron à six champs : le premier est celui des secondes. La valeur ci-dessus déclenche un passage à 5 h 00.
  • WATCHTOWER_CLEANUP supprime l'image précédente après recréation du conteneur, sinon les anciennes couches s'accumulent.
  • Aucune API HTTP n'est activée et aucune notification n'est configurée côté Watchtower : le suivi des mises à jour est assuré par un workflow n8n qui interroge docker-socket-proxy en lecture seule toutes les dix minutes et notifie sur Telegram.
Warning

Le montage de /var/run/docker.sock donne à ce conteneur un contrôle total de l'hôte. Il ne doit être ni publié, ni proxifié, ni placé sur un réseau partagé avec des services exposés.

Options disponibles, non utilisées ici

VariableEffetStatut
WATCHTOWER_POLL_INTERVALIntervalle de scrutation en secondes (300 par défaut)Remplacé par un cron
WATCHTOWER_ROLLING_RESTARTMet à jour les conteneurs un par unIncompatible avec les dépendances, voir ci-dessous
WATCHTOWER_MONITOR_ONLYDétecte et signale sans mettre à jourRôle tenu par n8n
WATCHTOWER_NO_PULLNe consulte que le cache d'images localUtile pour des images construites localement
WATCHTOWER_NO_RESTARTRecrée les conteneurs sans les démarrerPour un cycle de vie géré par systemd
WATCHTOWER_LABEL_ENABLEInverse la logique : seuls les conteneurs marqués enable=true sont suivisLa liste d'exclusions est plus courte que la liste d'inclusions
WATCHTOWER_DISABLE_CONTAINERSExclusion par nom de conteneur, expressions régulières acceptéesExclusions faites par label
WATCHTOWER_ENABLE_CONTAINERS_BY_LABELRestreint le suivi à des paires label=valeur
WATCHTOWER_SKIP_IMAGE_NAMESExclusion par nom d'image, tag inclus
WATCHTOWER_SCOPECloisonne plusieurs instances de Watchtower par label de portéeUne seule instance par machine
WATCHTOWER_INCLUDE_STOPPEDInclut les conteneurs créés ou sortis
WATCHTOWER_REVIVE_STOPPEDRedémarre les conteneurs arrêtés après mise à jour, exige include-stoppedLaisserait repartir les conteneurs volontairement arrêtés
WATCHTOWER_INCLUDE_RESTARTINGInclut les conteneurs en état restarting
WATCHTOWER_REMOVE_VOLUMESSupprime les volumes anonymes lors de la recréation, les volumes nommés ne sont pas touchés
WATCHTOWER_TIMEOUTDélai avant arrêt forcé d'un conteneur, 30s par défaut
WATCHTOWER_DISK_SPACE_MAXBloque la session de mise à jour au-delà d'un volume d'images donné
WATCHTOWER_DISK_SPACE_WARNSeuil d'avertissement, en taille ou en pourcentage du maximum
WATCHTOWER_USE_COMPOSE_DEPENDS_ONRespecte l'ordre imposé par depends_on, actif par défautLaissé à sa valeur par défaut
WATCHTOWER_LABEL_TAKE_PRECEDENCEDonne la priorité aux labels sur les options globales
WATCHTOWER_HTTP_API_UPDATEExpose un point d'entrée de mise à jour à la demandeAPI non activée
WATCHTOWER_HTTP_API_TOKENJeton d'authentification de l'APIAPI non activée
WATCHTOWER_HTTP_API_METRICSExpose des métriques PrometheusAPI non activée
WATCHTOWER_NOTIFICATION_URLNotifications Shoutrrr (Telegram, courriel, Gotify…)Notifications assurées par n8n
WATCHTOWER_EPHEMERAL_SELF_UPDATEAuto-mise à jour par conteneur orchestrateur éphémèreExpérimental
Warning

rolling-restart ne fonctionne pas dès qu'un conteneur suivi possède une dépendance : depends_on Compose, label depends-on, lien Docker ou network_mode pointant vers un autre conteneur. Le fork refuse alors de démarrer. L'option a été retirée de la stack pour cette raison.

Exclusions

Les conteneurs portant le label com.centurylinklabs.watchtower.enable=false sont ignorés, sans autre configuration côté Watchtower.

ConteneurRaison de l'exclusion
Reverse proxyToute la chaîne d'accès aux services en dépend, une régression coupe l'accès distant à la machine
Authentification uniqueUn changement de schéma de configuration bloque l'authentification de tous les services protégés
Détection et bannissementConfiguration sensible (acquisition, profils, bouncers) susceptible d'évoluer d'une version à l'autre
Base de données applicativeUn changement de version majeure du moteur peut déclencher une migration de schéma irréversible

Déclaration dans la stack du service concerné :

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

Ces quatre conteneurs se mettent à jour manuellement, après lecture des notes de version, en dehors des fenêtres de sauvegarde.

Autres labels reconnus

LabelEffet
com.centurylinklabs.watchtower.enabletrue ou false, inclut ou exclut le conteneur
com.centurylinklabs.watchtower.monitor-onlyDétecte la nouvelle image sans recréer le conteneur
com.centurylinklabs.watchtower.no-pullN'interroge pas le registre pour ce conteneur
com.centurylinklabs.watchtower.scopeRattache le conteneur à une instance de Watchtower donnée
com.centurylinklabs.watchtower.depends-onOrdre de mise à jour explicite, indépendant de Compose
com.centurylinklabs.watchtower.lifecycle.pre-update-commandCommande exécutée dans le conteneur avant l'arrêt
com.centurylinklabs.watchtower.lifecycle.post-update-commandCommande exécutée après le démarrage de la nouvelle instance

Commandes utiles

# Journaux du dernier passage
docker logs --tail 100 watchtower

# Vérifier la planification prise en compte au démarrage
docker logs watchtower | grep -i -e schedule -e "next run"

# Conteneurs actuellement exclus
docker ps --filter "label=com.centurylinklabs.watchtower.enable=false"

# Vérifier les labels Watchtower d'un conteneur
docker inspect <NOM_CONTENEUR> | grep -i watchtower

# Passage immédiat, sans toucher au conteneur planifié
docker run --rm \
  -v /var/run/docker.sock:/var/run/docker.sock \
  nickfedor/watchtower --run-once --cleanup <NOM_CONTENEUR>

# Contrôle à blanc : signale les images obsolètes sans rien recréer
docker run --rm \
  -v /var/run/docker.sock:/var/run/docker.sock \
  nickfedor/watchtower --run-once --monitor-only

# Prise en compte d'un changement de variable : redéployer la stack
Information

La sauvegarde nocturne est déclenchée à 3 h 30, Watchtower à 5 h. Une mise à jour défaillante est donc toujours précédée d'un point de restauration de la nuit même.