By Boris Mallach — 26 oct. 2026

Tutoriel : Migration d'un serveur Stalwart de la v0.16 vers la v1.0 et vérification du bon fonctionnement

Quelques éléments de ce tutoriel necessitent d'avoir au préalable suivi celui-ci.

Introduction

Avec l'arrivée de la version 1.0, Stalwart fige son schéma de base de données. Les versions antérieures (v0.16) ne peuvent pas être converties directement « sur place ». L'outil officiel stalwart-migrate permet de dupliquer de manière sécurisée et incrémentale les paramètres et les boîtes aux lettres vers un nouveau format stable, tout en préservant les identifiants de messages et les UIDs IMAP pour les clients finaux.

Étape 1 : Installation de l'outil de migration officiel

Sur le serveur hébergeant le service de messagerie (exécuté avec les privilèges d'administration), téléchargez et installez l'utilitaire de migration :

curl --proto '=https' --tlsv1.2 -LsSf https://github.com/stalwartlabs/stalwart-migrate/releases/latest/download/stalwart-migrate-installer.sh | sudo sh

Vérification : stalwart-migrate --version doit renvoyer 1.0.0.

Étape 2 : Configuration du nouveau stockage cible (v1.0)

Préparez un répertoire vierge qui accueillera la base de données au format v1.0 (par exemple, en conservant le backend RocksDB) :

sudo install -d -m 0750 -o stalwart -g stalwart /etc/stalwart-v1
sudo install -d -m 0750 -o stalwart -g stalwart /var/lib/stalwart-v1
sudo install -d -m 0750 -o root -g root /var/lib/stalwart-migrate

sudo tee /etc/stalwart-v1/config.json > /dev/null << 'EOF'
{
  "@type": "RocksDb",
  "path": "/var/lib/stalwart-v1/"
}
EOF
sudo chown stalwart:stalwart /etc/stalwart-v1/config.json

Étape 3 : Analyse et préparation de la migration

Lancez l'assistant de préparation pour convertir automatiquement les anciens paramètres vers la structure v1.0 :

sudo stalwart-migrate prepare \
  --source /etc/stalwart/config.json \
  --state /var/lib/stalwart-migrate

Contrôle : Vous pouvez consulter le rapport détaillé des éventuels ajustements ou adaptations de clés de configuration dans /var/lib/stalwart-migrate/prepare-report.txt.

Étape 4 : Synchronisation des données à chaud (zéro coupure)

Exécutez une première passe de copie pendant que le serveur de messagerie continue de fonctionner normalement :

sudo stalwart-migrate run \
  --source /etc/stalwart/config.json \
  --target /etc/stalwart-v1/config.json \
  --state /var/lib/stalwart-migrate \
  --owner "$(id -u stalwart):$(id -g stalwart)"

Note : L'option --owner garantit que les fichiers générés appartiennent bien au démon d'exécution stalwart.

Étape 5 : Arrêt du service et synchronisation finale

Une fois la base prégénérée, planifiez une courte fenêtre de maintenance, stoppez l'ancien service, puis effectuez la synchronisation des derniers éléments modifiés :

sudo systemctl stop stalwart

sudo stalwart-migrate run --final \
  --source /etc/stalwart/config.json \
  --target /etc/stalwart-v1/config.json \
  --state /var/lib/stalwart-migrate \
  --owner "$(id -u stalwart):$(id -g stalwart)"

Validez l'invitation en tapant yes lorsque demandé.

Vérifiez l'absence d'erreurs :

sudo stalwart-migrate report --state /var/lib/stalwart-migrate --severity error

Étape 6 : Bascule vers le binaire Stalwart v1.0.0

Pointez la configuration active vers le nouveau magasin de données migré :

sudo cp -a /etc/stalwart/config.json /etc/stalwart/config.json.016.bak
sudo cp -a /etc/stalwart-v1/config.json /etc/stalwart/config.json
sudo chown stalwart:stalwart /etc/stalwart/config.json

Mettez à jour le binaire vers la version officielle v1.0.0 à l'aide de votre script d'administration système :

sudo stalwart-upgrade v1.0.0

Étape 7 : Vérification du bon fonctionnement et de la délivrabilité

Validation de la réputation et de la configuration DNS :
- Testez l'envoi d'un e-mail depuis votre instance vers un service externe spécialisé (type Mail-tester.com) pour vérifier l'obtention d'un score de 10/10.
- Vérifiez que les enregistrements d'authentification (SPF, DKIM, DMARC) sont validés par les serveurs distants.

Contrôle de l'état du service systemd :

sudo systemctl status stalwart
sudo journalctl -u stalwart -n 50 --no-pager

Assurez-vous que le statut retourne bien active (running) sans boucle d'erreur.

Conclusion

La migration vers Stalwart 1.0 garantit désormais la stabilité pérenne du schéma de données et d'excellentes performances de traitement. Grâce à l'utilisation combinée de l'outil de migration officiel et d'une stricte vérification des flux de messagerie, l'infrastructure est prête pour une exploitation sereine et sécurisée en production.