Mettre à jour une stack Docker Compose en production

Pourquoi `latest` est le vrai coupable

Ce que ce guide couvre — et ce qu'il ne couvre pas

• Ce que ce guide couvre : le protocole pas-à-pas pour mettre à jour une stack Docker Compose sur un VPS — pinning de version, sauvegarde de volumes, vérification des notes de version, rollback rapide, healthchecks comme garde-fou.
• Prérequis couverts par d'autres guides : la checklist de durcissement initiale (docker-compose-production-checklist), la configuration de depends_on et service_healthy (docker-compose-depends-on-healthcheck), et la comparaison des outils de mise à jour automatique comme Watchtower ou Diun.
• Ce que ce guide ne recommande pas : Watchtower ou tout outil d'auto-pull en production — c'est précisément le contre-patron que les cas de breaking changes illustrent.
• Public cible : développeurs et agences qui gèrent une ou plusieurs stacks Docker Compose en production sur VPS, avec accès root et volumes persistants.

Étape 1 — Épingler toutes vos images

docker inspect --format='{{index .RepoDigests 0}}' getmeili/meilisearch:v1.53.0

Protocole de mise à jour — les 5 étapes

1. 01

   Lire les notes de version avant de puller

   Avant tout, consultez les release notes de la nouvelle version. Cherchez les mots breaking, migration, incompatible, pg_upgrade, dump. Ce n'est pas facultatif : Supabase a documenté explicitement que la mise à jour de PostgreSQL 15 vers 17 exige un pg_upgrade manuel — le conteneur PG 17 refuse de démarrer sur un volume PG 15, et le processus d'initialisation ne migre pas automatiquement les données.

   Pour Langfuse v4 (sorti le 17 août 2026), les SDKs Python v2 et antérieurs sont rejetés à l'ingestion par le nouveau stack — une rupture qui affecte tous les services clients qui tracent via l'ancienne API.

   Trois minutes de lecture vous évitent plusieurs heures de récupération de données.

2. 02

   Sauvegarder les volumes avant le pull

   Ne pullez jamais avant d'avoir un backup exploitable. Pour les volumes nommés, deux approches :

   Dump applicatif (recommandé pour les bases de données) — le service doit être healthy avant de dumper :

   docker compose exec db pg_dump -U postgres -Fc mydb > backup_$(date +%Y%m%d_%H%M%S).dump

   Snapshot de volume brut — utile pour les stockages binaires (Meilisearch, Redis, MinIO) :

   docker run --rm \
     --volumes-from $(docker compose ps -q meilisearch) \
     -v $(pwd)/backups:/backup \
     alpine tar czf /backup/meili_$(date +%Y%m%d_%H%M%S).tar.gz /meili_data

   Vérifiez que le backup est lisible avant de continuer. Un fichier de dump corrompu découvert pendant la récupération est le scénario le plus coûteux qui soit.

3. 03

   Puller la nouvelle image et tester hors ligne

   Mettez à jour le tag dans votre docker-compose.yml, puis pullez l'image sans redémarrer le service :

   docker compose pull meilisearch

   Si votre environnement le permet, testez la nouvelle image sur un clone du volume dans un environnement ddev ou sur une VM de staging avant de toucher à la production. Vérifiez dans les logs de démarrage qu'aucune erreur de migration ne s'affiche :

   docker compose up -d meilisearch
   docker compose logs -f meilisearch

   Attendez que le healthcheck passe à healthy avant de valider. Un service qui démarre mais qui n'est pas encore healthy n'est pas un service prêt.

4. 04

   Vérifier les healthchecks

   Un healthcheck bien configuré est votre première ligne de détection. Il doit être présent sur chaque service critique de la stack, au format Compose v2 :

   healthcheck:
     test: ["CMD-SHELL", "curl -sf http://localhost:7700/health || exit 1"]
     interval: 10s
     timeout: 5s
     retries: 5
     start_period: 30s

   Le champ start_period est critique pour les services à démarrage lent (bases de données, moteurs de recherche) : il évite que Docker déclare le conteneur unhealthy pendant la phase d'initialisation et déclenche un redémarrage prématuré.

   Consultez docker-compose-depends-on-healthcheck pour la configuration complète de service_healthy sur PostgreSQL — le même principe s'applique à tout service qui a besoin d'un temps d'amorçage.

5. 05

   Rollback en cas de problème

   Si la nouvelle version ne démarre pas ou produit des erreurs, le rollback doit prendre moins de deux minutes. La procédure :

   1. Revenez au tag précédent dans docker-compose.yml (ou git revert si vous avez commité le bump).
   2. Relancez uniquement le service concerné, sans recréer les volumes :

   docker compose up -d --no-deps --force-recreate meilisearch

   3. Vérifiez immédiatement les logs :

   docker compose logs -f meilisearch

   Le flag --no-deps est essentiel : il redémarre le service cible sans toucher aux autres conteneurs (base de données, cache, proxy). Sans lui, docker compose up -d peut recréer la totalité de la stack.

   ⚠️ Si la nouvelle version a migré le format des données sur disque (cas Meilisearch v1.54, Supabase PG17), le rollback d'image ne suffit pas — c'est pourquoi le backup du volume est une précondition, pas une option.

Les breaking changes récents qui ont cassé des instances

Stratégies de mise à jour : comparatif

Faites défiler le tableau

Intégrer ce protocole dans votre workflow

# .env
MEILISEARCH_VERSION=v1.53.0
POSTGRES_VERSION=15.6

# docker-compose.yml
services:
  meilisearch:
    image: getmeili/meilisearch:${MEILISEARCH_VERSION}