Watchtower : Mettre à jour automatiquement vos conteneurs Docker

🎯 Objectif

Gérer manuellement les mises à jour de conteneurs Docker peut vite devenir fastidieux, surtout en production avec de nombreux services. Watchtower est un outil open source qui surveille vos conteneurs en cours d'exécution et les met automatiquement à jour dès qu'une nouvelle version de leur image est publiée sur le registry.

Dans cet article, nous allons voir comment déployer et configurer Watchtower, gérer les notifications et adopter les bonnes pratiques pour une utilisation sereine en production.

🔧 Prérequis

• Docker installé et fonctionnel sur votre hôte
• Accès à un terminal avec les droits suffisants (groupe docker ou sudo)
• (Optionnel) Docker Compose pour une configuration déclarative

🚀 Démarrage rapide

La façon la plus simple de lancer Watchtower est d'utiliser docker run :

docker run -d \
  --name watchtower \
  -v /var/run/docker.sock:/var/run/docker.sock \
  nickfedor/watchtower:latest

Que fait cette commande ?

• Lance Watchtower en arrière-plan (-d).
• Monte le socket Docker (/var/run/docker.sock) pour que Watchtower puisse interroger et contrôler le daemon Docker local.
• Par défaut, Watchtower vérifie les mises à jour toutes les 24 heures et met à jour tous les conteneurs en cours d'exécution.

📋 Déploiement avec Docker Compose

Pour une configuration plus maintenable, intégrez Watchtower dans votre fichier docker-compose.yml :

services:
  watchtower:
    image: nickfedor/watchtower:latest
    container_name: watchtower
    restart: unless-stopped
    volumes:
      - /var/run/docker.sock:/var/run/docker.sock
    environment:
      - WATCHTOWER_POLL_INTERVAL=300         # Vérification toutes les 5 minutes
      - WATCHTOWER_CLEANUP=true              # Supprime les anciennes images
      - WATCHTOWER_LABEL_ENABLE=true         # Surveille uniquement les conteneurs avec le label enable=true

Puis lancez-le :

docker compose up -d

⚙️ Options essentielles

Intervalle de vérification

Par défaut : 86400 secondes (24h). Pour changer l'intervalle, utilisez la variable WATCHTOWER_POLL_INTERVAL (en secondes) :

environment:
  - WATCHTOWER_POLL_INTERVAL=3600  # Toutes les heures

Vous pouvez aussi utiliser une expression cron avec WATCHTOWER_SCHEDULE :

environment:
  - WATCHTOWER_SCHEDULE=0 0 4 * * *  # Tous les jours à 4h du matin

Nettoyage automatique des images

Après mise à jour, les anciennes images restent sur le disque. Activez le nettoyage automatique :

environment:
  - WATCHTOWER_CLEANUP=true

Surveillance sélective des conteneurs

Par défaut, Watchtower surveille tous les conteneurs. Pour ne surveiller que certains d'entre eux, utilisez des labels dans vos services :

services:
  mon-app:
    image: mon-registry/mon-app:latest
    labels:
      - "com.centurylinklabs.watchtower.enable=true"

  base-de-donnees:
    image: postgres:16
    labels:
      - "com.centurylinklabs.watchtower.enable=false"  # Exclure ce conteneur

Activez ensuite le mode opt-in dans Watchtower :

environment:
  - WATCHTOWER_LABEL_ENABLE=true  # Surveille uniquement les conteneurs avec enable=true

🔐 Registries privés

Si vos images sont hébergées sur un registry privé (Docker Hub privé, Harbor, GitLab Registry, GHCR…), vous devez fournir les identifiants à Watchtower.

Via un fichier de configuration Docker

Connectez-vous d'abord avec docker login sur votre hôte :

docker login registry.example.com

Puis montez le fichier de configuration dans le conteneur Watchtower :

services:
  watchtower:
    image: nickfedor/watchtower:latest
    volumes:
      - /var/run/docker.sock:/var/run/docker.sock
      - /root/.docker/config.json:/config.json
    environment:
      - DOCKER_CONFIG=/config.json

Via des variables d'environnement

environment:
  - REPO_USER=mon-utilisateur
  - REPO_PASS=mon-mot-de-passe

🔔 Notifications

Watchtower peut vous notifier à chaque mise à jour via plusieurs canaux.

Notification par e-mail

environment:
  - WATCHTOWER_NOTIFICATIONS=email
  - WATCHTOWER_NOTIFICATION_EMAIL_FROM=watchtower@example.com
  - WATCHTOWER_NOTIFICATION_EMAIL_TO=admin@example.com
  - WATCHTOWER_NOTIFICATION_EMAIL_SERVER=smtp.example.com
  - WATCHTOWER_NOTIFICATION_EMAIL_SERVER_PORT=587
  - WATCHTOWER_NOTIFICATION_EMAIL_SERVER_USER=smtp-user
  - WATCHTOWER_NOTIFICATION_EMAIL_SERVER_PASSWORD=smtp-password

Notification via Slack (ou tout webhook)

environment:
  - WATCHTOWER_NOTIFICATIONS=slack
  - WATCHTOWER_NOTIFICATION_SLACK_HOOK_URL=https://hooks.slack.com/services/XXX/YYY/ZZZ
  - WATCHTOWER_NOTIFICATION_SLACK_IDENTIFIER=watchtower-prod

Watchtower supporte aussi Gotify, Shoutrrr, MSTeams et d'autres systèmes de notification via l'intégration Shoutrrr.

🛡️ Bonnes pratiques

Utiliser des tags de version plutôt que latest

Watchtower fonctionne en comparant le digest de l'image locale avec celui disponible sur le registry. Si vous utilisez le tag latest, toute nouvelle publication déclenchera une mise à jour. Pour plus de contrôle, pointez sur un tag de version mineure et gérez vous-même la montée de version majeure :

image: nginx:1.27  # Watchtower mettra à jour les patchs de 1.27.x

Mode monitoring seul

Pour auditer sans toucher à rien, activez le mode lecture seule :

environment:
  - WATCHTOWER_MONITOR_ONLY=true

Watchtower détectera les mises à jour disponibles et enverra des notifications sans redémarrer aucun conteneur. Idéal pour commencer progressivement.

Délai de démarrage des conteneurs

Après la recréation d'un conteneur, Watchtower peut attendre un délai avant de passer au suivant, pour éviter des cascades de redémarrages :

environment:
  - WATCHTOWER_TIMEOUT=30s  # Attend 30 secondes avant de stopper l'ancien conteneur

Exécution unique (one-shot)

Pour déclencher une vérification manuelle et ponctuelle sans laisser Watchtower tourner en permanence :

docker run --rm \
  -v /var/run/docker.sock:/var/run/docker.sock \
  nickfedor/watchtower:latest --run-once

Cela peut s'intégrer dans un pipeline CI/CD pour déclencher les mises à jour après un push.

📝 Exemple complet docker-compose.yml

Voici un fichier docker-compose.yml prêt à l'emploi réunissant les options les plus utiles :

services:
  watchtower:
    image: nickfedor/watchtower:latest
    container_name: watchtower
    restart: unless-stopped
    volumes:
      - /var/run/docker.sock:/var/run/docker.sock
      - /root/.docker/config.json:/config.json
    environment:
      - DOCKER_CONFIG=/config.json
      - WATCHTOWER_POLL_INTERVAL=300       # Vérification toutes les 5 minutes
      - WATCHTOWER_CLEANUP=true
      - WATCHTOWER_LABEL_ENABLE=true
      - WATCHTOWER_NOTIFICATIONS=slack
      - WATCHTOWER_NOTIFICATION_SLACK_HOOK_URL=${SLACK_WEBHOOK_URL}
      - WATCHTOWER_NOTIFICATION_SLACK_IDENTIFIER=watchtower-prod
      - TZ=Europe/Paris

✅ Conclusion

Watchtower est un outil simple mais puissant pour maintenir vos conteneurs à jour sans intervention manuelle. Grâce à ses nombreuses options — surveillance sélective par labels, planification cron, notifications multi-canaux et mode monitoring seul — il s'adapte aussi bien aux environnements homelab qu'aux infrastructures de production.

Pour aller plus loin :

• nickfedor/watchtower sur GitHub — le fork activement maintenu
• Coupler Watchtower à un système de registry privé comme Harbor ou GitLab Container Registry pour un pipeline de déploiement continu complet.