Mettre à jour Mattermost v10 vers v11 LTS

Pourquoi mettre à jour maintenant

Mattermost publie des versions ESR (Extended Support Release) avec une durée de vie étendue, puis déclare leur fin de vie à une date annoncée à l'avance. L'ESR v10.11 est en fin de vie depuis le 15 août 2026. À partir de cette date, aucun correctif de sécurité n'est backporté sur cette branche : les vulnérabilités découvertes après la date d'EOL restent ouvertes sur les instances qui ne migrent pas.

Une messagerie d'équipe reçoit des pièces jointes, des identifiants partagés en DM, parfois des clés d'API posées en message. Une instance non patchée expose ces données à tout correctif non appliqué. La v11 est la LTS en cours de cycle — c'est la seule version qui recevra des correctifs pendant encore plusieurs mois.

Ce que la v11 LTS apporte par rapport à l'ESR v10.x

Correctifs de sécurité actifs — la branche reçoit les patchs de sécurité publiés par l'équipe Mattermost tout au long de son cycle de support.
Améliorations de performance — optimisations de requêtes PostgreSQL et réduction de la consommation mémoire sous forte charge.
Interface des appels vidéo retravaillée — qualité et stabilité améliorées pour les appels en canaux.
Plugins mis à jour — les plugins officiels (Calls, Boards, Playbooks) ont des versions compatibles v11 publiées dans le gestionnaire de plugins.
Corrections de migration de base de données — des migrations cumulées depuis v10 sont appliquées proprement, ce qui améliore l'intégrité à long terme du schéma.
Support étendu — la v11 LTS bénéficiera d'une fenêtre de support prolongée, vous évitant une nouvelle migration à brève échéance.

Prérequis avant de commencer

Vérifiez les points suivants avant de lancer la procédure.

Docker Compose v2 — la commande doit répondre docker compose version (avec espace, pas un tiret). Si vous avez encore docker-compose v1, migrez d'abord vers Compose v2 : les images officielles Mattermost v11 supposent ce format.

Accès root ou sudo sur le VPS — les commandes qui suivent agissent sur les volumes Docker et les fichiers de configuration.

Espace disque disponible — vérifiez avec df -h que le volume qui héberge vos volumes Docker dispose d'au moins 3 Go libres pour les dumps et les images temporaires.

RAM suffisante — Mattermost v11 tourne correctement avec 2 Go de RAM pour moins de 50 utilisateurs actifs. Vérifiez avec free -m avant la mise à jour.

Version actuelle notée — avant toute opération, notez la version installée : docker exec <mattermost-container> mattermost version. Ce point est l'étape 1 de la procédure.

Procédure de mise à jour pas à pas

Noter la version actuelle

Avant de modifier quoi que ce soit, relevez la version en cours :

docker exec mattermost mattermost version

Notez le numéro (par exemple v10.11.2). Cette référence vous permettra de comparer après la mise à jour et de prouver que la migration a bien eu lieu.

Sauvegarder la base PostgreSQL

C'est l'étape la plus critique. Exécutez un pg_dump depuis le conteneur PostgreSQL :

docker exec <pg-container> pg_dump -U mattermost mattermost > backup_mattermost_$(date +%Y%m%d).sql

Remplacez <pg-container> par le nom réel de votre conteneur (visible avec docker ps). Vérifiez que le fichier .sql créé n'est pas vide (ls -lh backup_mattermost_*.sql). Sans cette sauvegarde, toute migration BDD échouée est irréversible.

Sauvegarder les volumes Docker

Sauvegardez également les volumes Mattermost (configuration, données, plugins) :

tar czf mattermost_volumes_$(date +%Y%m%d).tar.gz /opt/mattermost/config /opt/mattermost/data /opt/mattermost/plugins /opt/mattermost/logs

Adaptez le chemin à votre installation (/opt/mattermost est le répertoire standard du dépôt officiel mattermost-docker). Déplacez l'archive hors du VPS sur un stockage externe avant de continuer.

Noter les plugins actifs

Depuis le System Console → Plugins → Plugin Management, listez tous les plugins activés avec leur version. Notez-les dans un fichier texte : après la mise à jour, vous devrez vérifier la compatibilité de chacun.

Alternativement, via l'API :

curl -s -H "Authorization: Bearer <votre-token>" https://chat.votredomaine.com/api/v4/plugins | python3 -m json.tool | grep -E '"id"|"version"|"active"'

Couper Mattermost et PostgreSQL

Arrêtez la stack proprement avant de tirer les nouvelles images :

docker compose down

Vérifiez qu'aucun conteneur Mattermost ne tourne encore : docker ps | grep mattermost.

Tirer les nouvelles images

Depuis le répertoire contenant votre docker-compose.yml :

docker compose pull

Cette commande télécharge les nouvelles images pour tous les services déclarés (mattermost et postgres). Si votre docker-compose.yml épingle une version explicite (mattermost/mattermost-team-edition:v10.x.x), mettez-la à jour vers v11 ou vers latest (puis épinglez ensuite le digest précis pour la reproductibilité).

Redémarrer la stack

Relancez l'ensemble des services :

docker compose up -d

Mattermost démarre, détecte que la base est à un schéma v10 et lance les migrations automatiquement. Cette étape peut prendre de 30 secondes à quelques minutes selon la taille de votre base.

Vérifier les migrations de base de données

Suivez les logs immédiatement après le démarrage :

docker compose logs mattermost | grep -i migrat

Les lignes attendues ressemblent à Running migration X.Y ou Migrating database from version X. Si vous voyez failed to run migrations ou error running migration, arrêtez (docker compose down) et restaurez depuis le dump avant d'aller plus loin.

Pour suivre en direct : docker compose logs -f mattermost — attendez le message Server is listening on.

Vérifier la nouvelle version

Confirmez que la mise à jour est bien effective :

docker exec mattermost mattermost version

La sortie doit afficher un numéro v11.x.x. Connectez-vous à l'interface web et naviguez dans System Console → About → Mattermost Server pour croiser la vérification.

Tester les fonctionnalités critiques

Avant de valider la mise à jour, testez manuellement les points suivants :

- Connexion d'un compte utilisateur
- Envoi et réception d'un message dans un canal public
- Envoi d'un message direct
- Envoi d'un fichier joint
- Vérification de l'historique des messages antérieurs à la mise à jour
- Fonctionnement des webhooks entrants si vous en avez configuré

L'historique complet doit rester accessible : c'est le premier point à vérifier.

Vérifier les plugins

Dans System Console → Plugins → Plugin Management, comparez la liste avec les notes prises à l'étape 4. Pour chaque plugin activé :

1. Vérifiez qu'il s'affiche toujours comme actif.
2. Si un plugin est désactivé avec un message d'incompatibilité, consultez la page de son dépôt pour une version compatible v11.
3. Mettez à jour depuis le gestionnaire de plugins si une nouvelle version est disponible.

Les plugins officiels (Calls, Boards, Playbooks) ont leurs versions v11 disponibles dans le marketplace intégré.

Nettoyer les anciennes images Docker

Une fois la mise à jour validée, libérez l'espace occupé par les anciennes images :

docker image prune -f

Cette commande supprime toutes les images non référencées par un conteneur actif. Elle peut récupérer plusieurs gigaoctets si vous avez conservé plusieurs versions d'images Mattermost.

Toujours tester la mise à jour hors production d'abord

Si vous administrez une instance en production avec de nombreux utilisateurs, reproduisez l'opération sur un environnement de test au préalable. Restaurez une copie de votre dump PostgreSQL sur un VPS de test, lancez la procédure complète, et vérifiez le résultat. Cela vous révèle les incompatibilités de plugins et les éventuelles erreurs de migration avant qu'elles n'affectent vos utilisateurs.

Compatibilité des plugins après la mise à jour

La v11 a introduit des changements dans l'API des plugins. La majorité des plugins officiels et des plugins actifs de la communauté sont compatibles, mais des incompatibilités peuvent apparaître sur des plugins anciens non maintenus.

Comment vérifier la compatibilité : rendez-vous dans System Console → Plugins → Plugin Management. Un plugin incompatible s'affiche avec un statut d'erreur et un message précisant la version minimale requise.

Si un plugin est incompatible :

1. Consultez le dépôt GitHub du plugin pour vérifier si une version compatible v11 a été publiée.
2. Si oui, téléchargez le .tar.gz et installez-le depuis System Console → Plugins → Upload Plugin.
3. Si non, évaluez si le plugin est critique. S'il l'est, signalez-le aux mainteneurs et gardez une copie de la v10 (votre dump) en attendant.

Les plugins officiels Mattermost (Calls, Boards, Playbooks, Jira, GitHub) sont mis à jour en même temps que le serveur et disponibles directement dans le marketplace intégré — vérifiez simplement qu'ils sont à leur dernière version disponible.

Dépannage : erreurs courantes

failed to run migrations dans les logs
La migration de base de données a échoué. Causes fréquentes : le conteneur PostgreSQL n'était pas démarré avant Mattermost (problème d'ordre de démarrage dans Compose), ou les permissions sur la base sont incorrectes. Arrêtez avec docker compose down, vérifiez que postgres démarre avant mattermost (clause depends_on dans docker-compose.yml), puis relancez. Si l'erreur persiste, restaurez le dump et examinez les logs complets avec docker compose logs mattermost 2>&1 | grep -i error.

Plugin marqué comme incompatible immédiatement après la mise à jour
Le plugin est lié à une API obsolète. Désactivez-le depuis la console (System Console → Plugins → Plugin Management → Désactiver) pour que Mattermost reste fonctionnel, puis mettez à jour le plugin séparément.

SIGTERM pendant la migration (conteneur arrêté en plein travail)
Si le conteneur Mattermost redémarre en cours de migration (timeout Docker, SIGTERM), la base peut se retrouver dans un état intermédiaire. Signe : mattermost version affiche un numéro hybride ou les logs montrent des erreurs de colonnes manquantes. Restaurez depuis le dump PostgreSQL et relancez en vous assurant que MATTERMOST_UPGRADE_TIMEOUT est configuré à une valeur suffisante (au minimum 600 secondes pour les grandes bases).

Problème de connexion après le redémarrage
Si l'interface répond mais les utilisateurs ne peuvent pas se connecter, vérifiez que MM_SERVICESETTINGS_SITEURL dans docker-compose.yml est bien en https:// et correspond exactement à l'URL que vous utilisez. Un changement de hostname ou de protocole pendant la mise à jour invalide les tokens de session existants.

Erreur database schema version mismatch
Mattermost détecte un écart entre la version du binaire et le schéma de la base. Ce cas survient si vous aviez épinglé une image v10 et que la migration partielle d'une tentative précédente a laissé le schéma dans un état v11 partiel. Restaurez le dump v10 complet, puis relancez la procédure depuis l'étape 5.

Après la mise à jour : bonnes pratiques

Une fois la v11 validée en production, quelques réglages maintiennent l'instance dans un état maîtrisé.

Épinglez la version d'image dans docker-compose.yml — remplacez latest par le tag précis (mattermost/mattermost-team-edition:v11.x.x). Cela évite qu'un docker compose pull ultérieur tire silencieusement une version future sans que vous l'ayez décidé.

Planifiez les sauvegardes PostgreSQL — un cron qui exécute pg_dump toutes les 24 heures et conserve les 7 derniers dumps est le minimum pour une instance de production.

Vérifiez le canal de sécurité Mattermost — abonnez-vous à https://mattermost.com/security-updates/ pour recevoir les annonces de CVE. La prochaine EOL de la v11 LTS sera annoncée plusieurs mois à l'avance.

Pour aller plus loin, retrouvez le guide d'installation initial dans l'article [Héberger Mattermost sur votre propre VPS](/blog/heberger-mattermost) et les arguments pour quitter Slack dans [Migrer de Slack vers Mattermost ou Rocket.Chat sur VPS](/blog/migration-slack-mattermost-rocketchat-vps).