--- title: "Architecture et prérequis" weight: 5 description: "Les trois processus de difuzio, le choix du backend de base de données et les prérequis d'une installation." --- # Architecture et prérequis difuzio (DIFfusion Unifiée vers Abonnés) est un moteur de listes de diffusion et de lettres d'information écrit en Go, pensé comme un successeur moderne de Sympa. Cette documentation s'adresse aux administrateurs système et aux exploitants qui installent, configurent et opèrent le service. Pour la documentation destinée aux abonnés et aux propriétaires de listes côté usage, voir le [guide de l'abonné](/difuzio/). ## Architecture en bref Un binaire unique, `difuzio`, expose plusieurs sous-commandes. En production, trois processus de longue durée partagent la même configuration et se coordonnent uniquement via la base de données (pas de bus de messages externe) : - `serve-web` : l'interface web (rendu serveur) et l'API REST `/api/v1`. C'est le seul processus exposé derrière un reverse proxy TLS. - `serve-lmtp` : la réception du courrier depuis Postfix via LMTP (posts vers les listes, commandes par email, bounces VERP, plaintes FBL). - `worker` : le pipeline de traitement des messages entrants, l'envoi sortant (relais SMTP), et les tâches périodiques (reaper, purge, expiration des tokens, évaluation du kill-switch de réputation). On en lance plusieurs pour le débit. La base de données est la source de vérité unique : la file d'envoi, les jobs entrants, les sessions, les compteurs de réputation, l'audit, tout y est. Les verrous applicatifs sérialisent les écritures concurrentes entre workers. ## Les deux profils de déploiement Le coeur de difuzio (pipeline, autorisations, transformations, fan-out) est le même dans tous les cas. Ce qui change d'une installation à l'autre, c'est par où le courrier entre et par où il sort. Deux profils sont documentés et supportés. **Profil MTA local** - difuzio a son propre serveur de messagerie : Internet -> MX Postfix -> LMTP (serve-lmtp) -> pipeline -> relais SMTP local -> abonnés **Profil boîte externe** - difuzio n'a qu'une boîte mail chez un hébergeur : Internet -> boîte hébergeur -> poller IMAP (boucle du worker) -> pipeline -> submission 587 AUTH -> abonnés Ce qui les sépare : | | MTA local | Boîte externe | |---|---|---| | Réception | LMTP depuis Postfix, adresse d'enveloppe classée (post, subscribe, unsubscribe, owner, bounce) | IMAP, une boîte = une liste (l'enveloppe SMTP est perdue, il n'y a rien à classer) | | Envoi | relais local, sans authentification | submission 587 STARTTLS + AUTH de l'hébergeur | | Abonnements | par courriel et par le web | par le web et le lien de désabonnement en un clic uniquement | | Rebonds | VERP, plaintes FBL, kill-switch de réputation | non traités automatiquement : un abonné dont l'adresse meurt se retire à la main | | SPF/DKIM/DMARC | à publier et à signer soi-même (le MTA frontal signe) | alignés nativement, l'hébergeur signe | | Débit | dimensionné par les pools d'envoi | plafonné par le quota de la boîte (souvent quelques centaines de messages par jour) | | Déploiement | multi-hôte possible | mono-hôte (le poller est un singleton) | | Prérequis | accès administrateur au MTA, MX, DNS | une boîte mail et ses identifiants | Les deux coutures sont indépendantes et se règlent **liste par liste** : une même instance peut recevoir en LMTP pour une liste et relever une boîte IMAP pour une autre, ou n'utiliser le compte SMTP d'un hébergeur que pour certaines listes. Un troisième axe, orthogonal, est le backend de base de données (MariaDB ou SQLite, section suivante) : SQLite et boîte externe se marient bien pour une petite installation autonome, mais rien n'oblige à les prendre ensemble. Un exploitant qui ne veut pas du profil boîte externe sur son serveur le ferme pour tout le monde avec `policy.external_mailboxes: deny` : aucun administrateur de domaine ne peut plus attacher un compte de fournisseur à une liste. Voir [Configuration](/difuzio/admin/configuration), section `policy`. Fermer le profil MTA local ne demande aucune option : il suffit de ne pas lancer `serve-lmtp`. Pour installer le profil boîte externe de bout en bout, suivre [Comptes de messagerie externes](/difuzio/admin/boite-externe). ## Backend de base de données difuzio se compile en deux variantes : la variante MariaDB (celle par défaut, pour un service multi-hôtes et à volume) et la variante SQLite (installation mono-hôte, faible volume, aucun serveur de base à administrer). Le choix se fait à la compilation, pas au démarrage. Voir [Base de données](/difuzio/admin/base-de-donnees) pour choisir, construire le bon binaire et connaître les limites de chacun. ## Prérequis Communs aux deux profils : - Un reverse proxy TLS devant `serve-web`. - Trois secrets (keyrings) d'au moins 32 octets, stockés en fichiers 0600, jamais en base. - MariaDB >= 10.6 (indispensable pour `FOR UPDATE ... SKIP LOCKED`). Une version antérieure fait échouer le démarrage (fatal, pas de repli silencieux). Avec la variante SQLite, aucun serveur de base n'est nécessaire. Propres au profil MTA local : - Postfix en frontal (réception LMTP) et en relais (submission/réinjection), avec un accès administrateur pour router le domaine et publier le DNS. Propres au profil boîte externe : - Une boîte mail par liste chez un hébergeur, avec IMAP et submission authentifié. Ni MX, ni Postfix, ni `serve-lmtp`. ## Par où commencer Les deux profils ne demandent pas la même lecture. **Profil boîte externe** (une boîte chez un hébergeur, pas de serveur mail à soi) : lire [Comptes de messagerie externes](/difuzio/admin/boite-externe), qui déroule l'installation complète, puis [Base de données](/difuzio/admin/base-de-donnees) pour la variante SQLite, [Proxy web frontal](/difuzio/admin/reverse-proxy), [Listes](/difuzio/admin/listes) et [Mails transactionnels](/difuzio/admin/mails-transactionnels). Les sections Postfix de [Installation](/difuzio/admin/installation) et de [Domaines](/difuzio/admin/domaines), ainsi que les parties rebonds et pools d'envoi de [Délivrabilité](/difuzio/admin/delivrabilite), ne s'appliquent pas : elles sont signalées comme telles sur place. **Profil MTA local** (Postfix devant difuzio) : suivre le sommaire ci-dessous dans l'ordre, en sautant [Comptes de messagerie externes](/difuzio/admin/boite-externe). ## Sommaire - [Installation et déploiement](/difuzio/admin/installation) - base de données, migrations, keyrings, systemd, intégration Postfix. - [Comptes de messagerie externes](/difuzio/admin/boite-externe) - le profil boîte externe de bout en bout : IMAP relevé, submission authentifié, comptes par liste, limites et verrou global. - [Base de données](/difuzio/admin/base-de-donnees) - MariaDB ou SQLite : choix, compilation, DSN, limites et sauvegarde. - [Configuration](/difuzio/admin/configuration) - le fichier `config.yaml` section par section, surcharge par variables d'environnement, invariants validés au démarrage. - [Proxy web frontal](/difuzio/admin/reverse-proxy) - exposer l'interface et l'API derrière Apache ou Nginx : TLS, en-têtes, vhosts complets. - [Domaines](/difuzio/admin/domaines) - provisionner un domaine, le router dans Postfix, vérifier le DNS, préparer la délivrabilité. - [Listes](/difuzio/admin/listes) - créer des listes, choisir le type, régler les politiques (post, abonnement, archives, reply-to, munging). - [Mails transactionnels](/difuzio/admin/mails-transactionnels) - les courriers envoyés aux abonnés hors diffusion : confirmation, bienvenue, adieu, lien de connexion ; langue du domaine, textes personnalisables, forme HTML et texte. - [Utilisateurs et rôles](/difuzio/admin/utilisateurs-roles) - le modèle RBAC, le bootstrap du premier super_admin, l'octroi de rôles. - [Modération](/difuzio/admin/moderation) - la file de modération des messages et des abonnements, le kill-switch de réputation. - [Délivrabilité](/difuzio/admin/delivrabilite) - SPF/DKIM/DMARC/ARC, munging d'en-tête From, bounces, plaintes, pools d'envoi. - [API REST](/difuzio/admin/rest-api) - clés d'API, périmètre, points d'entrée existants, webhooks (avec garde anti-SSRF). - [Exploitation](/difuzio/admin/exploitation) - métriques Prometheus, sondes de santé, file d'envoi, sauvegarde, journaux et rétention. - [RGPD](/difuzio/admin/rgpd) - consentement, droit à l'effacement, rétention. - [Référence CLI](/difuzio/admin/cli-reference) - toutes les sous-commandes et leurs options. ## Conventions de cette documentation Tous les exemples de commandes utilisent le binaire `difuzio`. Les commandes d'administration prennent soit `--dsn `, soit `--config ` pour la connexion à la base. Les commandes daemon (`serve-web`, `serve-lmtp`, `worker`) prennent `--config ` et chargent les keyrings. Toutes les dates et heures manipulées par difuzio sont en UTC.