Exploitation

Cette section s’adresse à la personne qui fait tourner une instance Mankomail : vous l’avez installée avec Auto-hébergement, il reste à la configurer, la sauvegarder, la mettre à jour et la surveiller.

Page	Ce qu’elle couvre
Configuration	Comment se configure une instance, les secrets en fichier, l’adresse publique et le HTTPS, la clé de chiffrement, les envois, les modèles d’IA, la séparation entre API et workers.
Sauvegardes	Sauvegarder et restaurer pas à pas avec les scripts livrés avec le code source, et tester une restauration sans toucher à la production.
Mises à jour	Passer à une nouvelle version, le déroulement des migrations de base, l’ordre des processus, le retour arrière.
Supervision	Sondes de santé, journaux, ce qu’il faut surveiller, dimensionnement, et le comportement de l’instance après un redémarrage ou une coupure de la base.
Marque blanche	Votre nom, vos logos, vos couleurs et votre page de connexion, par variables d’environnement ou depuis un control plane ; ce que la liaison à un control plane envoie et reçoit, et la suspension.

Chaque variable d’environnement, avec sa valeur par défaut et ses valeurs acceptées, figure dans Variables d’environnement.

Les composants d’une instance

Une instance auto-hébergée compte peu d’éléments. Il n’y a ni Redis, ni courtier de messages, ni ordonnanceur séparé.

Composant	Rôle	Obligatoire
Application	Un processus qui sert l’API HTTP, l’interface web et le canal temps réel, et qui fait tourner le travail de fond : synchronisation des boîtes, exécutions des workflows, envois, tâches planifiées, entretien.	Oui
PostgreSQL	Porte tout l’état de l’instance, file de tâches comprise.	Oui
Stockage objet compatible S3	Porte les corps de mails, les pièces jointes et les fichiers ajoutés aux exécutions. Le fichier Docker Compose de référence fait tourner MinIO ; tout service compatible S3 convient.	Oui
Reverse proxy	Termine le HTTPS devant l’application, qui ne parle pas TLS elle-même.	Oui, pour toute instance jointe par le réseau

L’application est une seule image Docker. La même image tient tous les rôles : ce que fait un processus dépend de la variable APP_ROLE.

Les rôles de processus

APP_ROLE décide de ce que fait un processus applicatif.

APP_ROLE	API HTTP et interface web	Travail de fond
all (défaut)	Oui	Oui
api	Oui	Non
worker	Le processus écoute tout de même sur son port HTTP, ce qui permet à une sonde de santé de le joindre	Oui

• all est ce que fait tourner le fichier Compose de référence : un seul conteneur fait tout. C’est le bon choix pour la plupart des instances.
• api et worker permettent de dimensionner séparément les deux côtés. Un processus démarré avec APP_ROLE=api écrit un avertissement au démarrage (APP_ROLE=api: this process runs no worker), car sans au moins un processus worker ou all, rien ne se synchronise, aucun workflow ne s’exécute et rien ne part.
• Il n’y a pas de leader. Chaque processus de fond prend son travail dans la file stockée dans PostgreSQL : vous pouvez en faire tourner plusieurs côte à côte sans aucun réglage de coordination.

Pour la mise en place, voir Séparer API et workers.

Où vit chaque donnée

Donnée	Où elle vit	Dans la sauvegarde des scripts
Membres, sessions, boîtes et leur état de synchronisation, métadonnées des messages, workflows et leurs versions, exécutions, file de tâches, tables, journal d’audit	PostgreSQL	Oui, sous forme d’export de la base
Secrets enregistrés : jetons OAuth des boîtes, mots de passe IMAP, clés des fournisseurs d’IA, autres connexions, secrets des applications OAuth	PostgreSQL, chiffrés avec ENCRYPTION_KEY	Oui, toujours chiffrés
Corps de mails, pièces jointes, fichiers ajoutés aux exécutions	Stockage objet	Oui, sous forme de copie de chaque objet
ENCRYPTION_KEY, mots de passe de la base et du stockage, PUBLIC_BASE_URL	Votre fichier .env ou votre coffre à secrets	Non

Le miroir garde une copie locale de chaque boîte connectée : si vous perdez toute l’instance, les mails eux-mêmes existent toujours chez le fournisseur de messagerie. Ce qui n’existe que dans votre instance, c’est tout le reste : workflows, exécutions, tables, réglages, journal d’audit.

Ce qu’il faut sauvegarder

Trois choses, dont les scripts de sauvegarde ne couvrent que les deux premières :

1. La base PostgreSQL.
2. Le bucket du stockage objet.
3. ENCRYPTION_KEY, rangée ailleurs que les sauvegardes, par exemple dans un gestionnaire de mots de passe. Sans exactement la même clé, une instance restaurée affiche tous les mails, mais aucun secret enregistré n’est lisible et chaque boîte doit être reconnectée.

Gardez aussi une copie du reste du fichier .env : les mots de passe de la base et du stockage, et l’adresse publique. Voir Sauvegardes.

Ce que l’instance fait seule

Plusieurs opérations ne demandent rien de votre part :

• Les migrations de base s’appliquent automatiquement au démarrage de l’application, sous un verrou PostgreSQL, si bien que plusieurs processus peuvent démarrer en même temps. Voir Mises à jour.
• L’attente de la base. Au démarrage, l’application attend jusqu’à 60 secondes que PostgreSQL accepte les connexions, ce qui couvre une pile où l’application démarre la première.
• L’entretien. Une tâche d’entretien horaire supprime les données plus anciennes que leur durée de conservation (exécutions, essais, journal d’audit, opérations sortantes, etc.) et retire les objets dont les données supprimées n’ont plus besoin. Les durées figurent dans Variables d’environnement.
• La reprise après un crash. Une tâche de fond tenue par un processus mort est rendue à la file à l’expiration de son bail, puis reprise par un autre processus. Voir Supervision.
• Les coupures de la base. Un redémarrage ou une coupure de PostgreSQL n’arrête pas l’application : les requêtes échouent pendant la coupure, puis tout reprend au retour de la base, sans redémarrer l’application.

Avant de mettre une instance en production

• Réglez PUBLIC_BASE_URL sur l’adresse HTTPS exacte de l’instance, derrière un reverse proxy. Voir Configuration.
• Gardez une copie d’ENCRYPTION_KEY hors du serveur.
• Planifiez les sauvegardes, puis restaurez-en une sur une copie pour prouver qu’elle fonctionne. Voir Tester une restauration sans toucher à la production.
• Pointez une sonde de santé sur /healthz et une vérification externe sur /readyz. Voir Supervision.
• Vérifiez que les journaux ne remplissent pas le disque, et que le disque a la place des boîtes que vous synchronisez.