2. Architecture fonctionnelle de la V3

La V3 est organisée autour d’actions CLI. Chaque action produit un résultat concret : audit, installation, fichier, rapport, ZIP ou score. L’outil reste volontairement simple : un seul fichier Python, utilisable directement avec python3, sans framework externe obligatoire.

Actions disponibles

Sorties générées

3. Pré-requis avant d’utiliser l’outil

L’outil facilite énormément l’installation, mais il ne peut pas contourner les contraintes fondamentales d’un serveur mail. Avant de lancer une installation client, il faut vérifier l’infrastructure, le domaine, les DNS et la capacité du provider à autoriser l’émission SMTP.

Pré-requis serveur

Ports utilisés

Pré-requis DNS et réputation

• le domaine doit être modifiable côté DNS ;
• le sous-domaine serveur doit être clair, par exemple mail.example.com ;
• l’IP publique doit avoir un PTR/rDNS modifiable ;
• il ne doit pas y avoir deux SPF contradictoires ;
• les anciens MX doivent être supprimés lors de la bascule ;
• le domaine ne doit pas être massivement blacklisté avant démarrage ;
• la stratégie DMARC doit commencer prudemment puis durcir progressivement.

Pré-requis poste opérateur

ssh root@mail.example.com
scp mailcow_assisted_installer_v3.py root@mail.example.com:/root/
nslookup -type=mx example.com
dig TXT example.com
dig -x 1.2.3.4

4. Installer l’outil Mailcow Assisted Installer V3

L’outil est un script Python autonome. Il peut être exécuté directement depuis un dossier d’administration, par exemple /opt/ideolab-mail-installer ou /root/mailcow-installer. Pour une utilisation commerciale, il est préférable de conserver chaque mission client dans un dossier séparé avec ses rapports.

Téléchargement direct de l’installer

mkdir -p /root/mailcow-installer
cd /root/mailcow-installer

curl -fsSL https://www.ideo-lab.com/static/toolbox/mailcow_assisted_installer_v3.py \
  -o mailcow_assisted_installer_v3.py

python3 mailcow_assisted_installer_v3.py --help

Installation simple sur le serveur cible

mkdir -p /root/mailcow-installer
cd /root/mailcow-installer

# Option A: direct download from IDEO-Lab static toolbox.
curl -fsSL https://www.ideo-lab.com/static/toolbox/mailcow_assisted_installer_v3.py \
  -o mailcow_assisted_installer_v3.py

# Option B: copy from your workstation.
# scp mailcow_assisted_installer_v3.py root@mail.example.com:/root/mailcow-installer/

python3 --version
python3 mailcow_assisted_installer_v3.py --help

Installation depuis le ZIP de distribution

mkdir -p /root/mailcow-installer
cd /root/mailcow-installer
unzip mailcow_assisted_installer_v3_package.zip
python3 mailcow_assisted_installer_v3.py --help

Organisation conseillée

Premier test sans risque

sudo python3 mailcow_assisted_installer_v3.py all \
  --domain example.com \
  --hostname mail.example.com \
  --public-ip 1.2.3.4 \
  --target-volume 100000 \
  --service-tier 100k \
  --dry-run

5. Quick Start — parcours standard en 10 commandes

Ce parcours correspond à une mission classique : un client dispose d’un domaine, d’un VPS, d’une IP publique et veut installer Mailcow avec génération de tous les documents nécessaires.

1 — Créer un profil client

python3 mailcow_assisted_installer_v3.py profile-template \
  --report-dir ./reports

2 — Auditer le serveur

sudo python3 mailcow_assisted_installer_v3.py preflight \
  --domain example.com \
  --hostname mail.example.com \
  --public-ip 1.2.3.4 \
  --check-outbound-25 \
  --report-dir ./reports

3 — Générer le plan DNS

python3 mailcow_assisted_installer_v3.py dns-plan \
  --domain example.com \
  --hostname mail.example.com \
  --public-ip 1.2.3.4 \
  --report-dir ./reports

4 — Installer tout le système

sudo python3 mailcow_assisted_installer_v3.py all \
  --domain example.com \
  --hostname mail.example.com \
  --public-ip 1.2.3.4 \
  --target-volume 100000 \
  --service-tier 100k \
  --remove-conflicting-docker \
  --configure-ufw \
  --yes \
  --report-dir ./reports

5 — Générer la configuration Django

python3 mailcow_assisted_installer_v3.py django-snippet \
  --domain example.com \
  --hostname mail.example.com \
  --smtp-user noreply@example.com \
  --report-dir ./reports

python3 mailcow_assisted_installer_v3.py env-template \
  --domain example.com \
  --hostname mail.example.com \
  --smtp-user noreply@example.com \
  --report-dir ./reports

6 — Générer le warm-up plan

python3 mailcow_assisted_installer_v3.py warmup-plan \
  --domain example.com \
  --hostname mail.example.com \
  --target-volume 100000 \
  --service-tier 100k \
  --report-dir ./reports

7 — Lancer le doctor

python3 mailcow_assisted_installer_v3.py doctor \
  --domain example.com \
  --hostname mail.example.com \
  --public-ip 1.2.3.4 \
  --report-dir ./reports

8 — Tester les blacklists

python3 mailcow_assisted_installer_v3.py blacklist-doctor \
  --domain example.com \
  --hostname mail.example.com \
  --public-ip 1.2.3.4 \
  --report-dir ./reports

9 — Calculer le readiness score

python3 mailcow_assisted_installer_v3.py readiness-score \
  --domain example.com \
  --hostname mail.example.com \
  --public-ip 1.2.3.4 \
  --report-dir ./reports

10 — Générer le ZIP client

python3 mailcow_assisted_installer_v3.py delivery-pack \
  --client-name "Example Client" \
  --domain example.com \
  --hostname mail.example.com \
  --public-ip 1.2.3.4 \
  --smtp-user noreply@example.com \
  --target-volume 100000 \
  --service-tier 100k \
  --report-dir ./reports

6. Profil client JSON

Le profil client est utile pour éviter de répéter les mêmes paramètres dans toutes les commandes. Il devient aussi un document de cadrage de mission : domaine, hostname, IP, volume cible, tier commercial, utilisateur SMTP, dossier de rapports.

Créer le template

python3 mailcow_assisted_installer_v3.py profile-template \
  --report-dir ./reports

Exemple de profil client

{
  "client_name": "Example Client",
  "domain": "example.com",
  "hostname": "mail.example.com",
  "public_ip": "1.2.3.4",
  "ipv6": "",
  "timezone": "Europe/Madrid",
  "smtp_user": "noreply@example.com",
  "target_volume": 100000,
  "service_tier": "100k",
  "install_dir": "/opt/mailcow-dockerized",
  "report_dir": "./reports"
}

Utiliser le profil

python3 mailcow_assisted_installer_v3.py dns-plan \
  --profile ./reports/mailcow_client_profile.json

python3 mailcow_assisted_installer_v3.py delivery-pack \
  --profile ./reports/mailcow_client_profile.json

7. Gestion DNS avec l’outil

La partie DNS est le cœur de la délivrabilité. L’outil produit un plan clair, mais il ne peut pas toujours tout appliquer, parce que le DNS peut être chez GoDaddy, Cloudflare, OVH, Infomaniak, Gandi ou un autre registrar. La V3 automatise Cloudflare et documente les autres cas.

Générer le plan DNS

python3 mailcow_assisted_installer_v3.py dns-plan \
  --domain example.com \
  --hostname mail.example.com \
  --public-ip 1.2.3.4 \
  --report-dir ./reports

Enregistrements attendus

PTR / reverse DNS

Le PTR ne se configure généralement pas dans la zone DNS du domaine. Il se configure côté provider IP : Hetzner, OVH, AWS, Scaleway, etc. Il doit pointer vers le FQDN du serveur mail.

Contrôles manuels utiles

dig A mail.example.com +short
dig MX example.com +short
dig TXT example.com +short
dig TXT _dmarc.example.com +short
dig TXT dkim._domainkey.example.com +short
dig -x 1.2.3.4 +short

8. Application DNS avec Cloudflare

Lorsque la zone DNS du client est chez Cloudflare, l’outil peut créer ou mettre à jour automatiquement les enregistrements nécessaires. C’est très utile pour industrialiser une prestation. Il faut disposer d’un token API limité à la zone concernée.

Préparer le token

• créer un token Cloudflare limité à la zone du client ;
• donner le droit DNS Write ;
• ne jamais mettre le token en dur dans une commande conservée dans l’historique ;
• préférer une variable d’environnement temporaire.

export CLOUDFLARE_API_TOKEN="replace-me"

Appliquer les records

python3 mailcow_assisted_installer_v3.py dns-apply-cloudflare \
  --domain example.com \
  --hostname mail.example.com \
  --public-ip 1.2.3.4 \
  --cloudflare-zone-id ZONE_ID \
  --cloudflare-overwrite \
  --yes \
  --report-dir ./reports

Ce qui est appliqué

9. Installation Mailcow avec la V3

L’installation peut se faire action par action ou via all. Pour un client, le mode recommandé est : préflight, validation humaine, dry-run, puis installation réelle. L’outil protège contre certains cas dangereux : ports occupés, OS non supporté, Docker manquant ou trop ancien, RAM/disque insuffisants.

Installation complète recommandée

sudo python3 mailcow_assisted_installer_v3.py all \
  --domain example.com \
  --hostname mail.example.com \
  --public-ip 1.2.3.4 \
  --target-volume 100000 \
  --service-tier 100k \
  --remove-conflicting-docker \
  --configure-ufw \
  --yes \
  --report-dir ./reports

Installation sans démarrer les containers

sudo python3 mailcow_assisted_installer_v3.py install \
  --domain example.com \
  --hostname mail.example.com \
  --public-ip 1.2.3.4 \
  --no-start \
  --yes \
  --report-dir ./reports

Mode low-memory

Pour les petites machines, l’option --low-memory configure Mailcow pour désactiver certains composants gourmands. Ce n’est pas conseillé pour de gros volumes, mais c’est utile pour un lab ou une preuve de concept.

sudo python3 mailcow_assisted_installer_v3.py all \
  --domain example.com \
  --hostname mail.example.com \
  --public-ip 1.2.3.4 \
  --low-memory \
  --yes

Postcheck

sudo python3 mailcow_assisted_installer_v3.py postcheck \
  --domain example.com \
  --hostname mail.example.com \
  --public-ip 1.2.3.4 \
  --report-dir ./reports

Résultats attendus après installation

• /opt/mailcow-dockerized existe ;
• mailcow.conf est généré ;
• les containers Mailcow sont démarrés ;
• l’interface admin est disponible sur https://mail.example.com/admin ;
• le rapport JSON et le rapport HTML sont créés dans ./reports.

10. Intégration Django

Une partie importante de la prestation consiste à connecter l’application du client à son nouveau SMTP. La V3 génère un snippet Django et un fichier .env.example. Le mot de passe SMTP n’est pas écrit dans le code : il doit rester dans l’environnement.

Générer le snippet Django

python3 mailcow_assisted_installer_v3.py django-snippet \
  --domain example.com \
  --hostname mail.example.com \
  --smtp-user noreply@example.com \
  --smtp-password-env EMAIL_HOST_PASSWORD \
  --report-dir ./reports

Exemple de configuration générée

import os

EMAIL_BACKEND = "django.core.mail.backends.smtp.EmailBackend"
EMAIL_HOST = "mail.example.com"
EMAIL_PORT = 587
EMAIL_USE_TLS = True
EMAIL_HOST_USER = "noreply@example.com"
EMAIL_HOST_PASSWORD = os.environ.get("EMAIL_HOST_PASSWORD", "")
DEFAULT_FROM_EMAIL = "noreply@example.com"
SERVER_EMAIL = "noreply@example.com"

EMAIL_TIMEOUT = 20

Générer le fichier .env.example

python3 mailcow_assisted_installer_v3.py env-template \
  --domain example.com \
  --hostname mail.example.com \
  --smtp-user noreply@example.com \
  --smtp-password-env EMAIL_HOST_PASSWORD \
  --report-dir ./reports

Test depuis Django shell

python manage.py shell

from django.core.mail import send_mail

send_mail(
    "SMTP test",
    "This is a Mailcow SMTP test from Django.",
    "noreply@example.com",
    ["recipient@example.net"],
    fail_silently=False,
)

Checklist Django avant production

11. Warm-up IP et domaine

Le warm-up est indispensable. Même si l’installation est parfaite, un serveur neuf avec une IP neuve ne doit pas envoyer brutalement 100 000 emails. Les fournisseurs comme Gmail, Outlook ou Yahoo observent la réputation de l’IP, du domaine, du sous-domaine et des comportements d’envoi.

Générer un plan warm-up

python3 mailcow_assisted_installer_v3.py warmup-plan \
  --domain example.com \
  --hostname mail.example.com \
  --target-volume 100000 \
  --service-tier 100k \
  --report-dir ./reports

Exemple de progression

Règles d’arrêt immédiat

Livrables générés

• plan Markdown lisible par le client ;
• CSV exploitable dans Excel/Google Sheets ;
• rapport HTML/JSON de génération ;
• inclusion automatique dans le delivery pack.

12. Delivery Pack client

Le delivery-pack est la grande nouveauté commerciale de la V3. Il permet de livrer au client un dossier complet, structuré, réutilisable, qui prouve le travail réalisé et donne au client les consignes d’exploitation.

Créer le delivery pack

python3 mailcow_assisted_installer_v3.py delivery-pack \
  --client-name "Example Client" \
  --domain example.com \
  --hostname mail.example.com \
  --public-ip 1.2.3.4 \
  --smtp-user noreply@example.com \
  --target-volume 100000 \
  --service-tier 100k \
  --report-dir ./reports

Contenu du ZIP

Quand générer le delivery pack ?

• avant installation, pour présenter le plan au client ;
• après installation, pour livrer le dossier final ;
• après correction DNS, pour archiver une version propre ;
• avant une bascule en production, pour obtenir validation du client.

13. Doctor délivrabilité

Le mode Doctor est destiné à répondre à une question simple : le serveur est-il prêt à envoyer et recevoir correctement ? Il ne remplace pas un test réel Gmail/Outlook, mais il attrape les erreurs les plus fréquentes avant production.

Doctor DNS / SMTP

python3 mailcow_assisted_installer_v3.py doctor \
  --domain example.com \
  --hostname mail.example.com \
  --public-ip 1.2.3.4 \
  --report-dir ./reports

Blacklist Doctor

python3 mailcow_assisted_installer_v3.py blacklist-doctor \
  --domain example.com \
  --hostname mail.example.com \
  --public-ip 1.2.3.4 \
  --report-dir ./reports

Readiness Score

python3 mailcow_assisted_installer_v3.py readiness-score \
  --domain example.com \
  --hostname mail.example.com \
  --public-ip 1.2.3.4 \
  --report-dir ./reports

Contrôles réalisés

14. Backup configuration

La V3 inclut backup-config pour sauvegarder les fichiers de configuration importants. Ce n’est pas un backup complet des boîtes mail. C’est une sauvegarde de configuration destinée aux opérations de maintenance, audit et rollback léger.

Créer un backup config

sudo python3 mailcow_assisted_installer_v3.py backup-config \
  --domain example.com \
  --install-dir /opt/mailcow-dockerized \
  --report-dir ./reports \
  --yes

Ce qui est couvert

• mailcow.conf ;
• docker-compose.yml si présent ;
• fichiers de configuration locaux identifiés par l’outil ;
• rapport JSON/HTML associé.

Ce qui n’est pas couvert

Backup complet recommandé en production

Pour une offre client sérieuse, ajouter un vrai backup Mailcow : volumes Docker, base MariaDB, vmail, crypt, Redis, export distant vers Storage Box/S3/restic/borg, test de restauration, rétention, monitoring.

15. Exploitation quotidienne

Après installation, l’enjeu principal devient la stabilité : logs, queue SMTP, bounces, reputation, blacklist, backups, mises à jour et séparation des flux transactionnels/marketing.

Commandes Mailcow utiles

Routine hebdomadaire recommandée

• lancer doctor ;
• lancer blacklist-doctor ;
• vérifier la queue SMTP ;
• vérifier les bounces récents ;
• contrôler l’espace disque ;
• contrôler les backups ;
• vérifier la réputation Gmail/Outlook sur emails tests.

Routine avant campagne ou volume important

• ne jamais lancer une campagne massive depuis une IP neuve ;
• confirmer que SPF/DKIM/DMARC passent ;
• segmenter les destinataires ;
• surveiller queue et bounces pendant l’envoi ;
• avoir une procédure d’arrêt immédiat ;
• ne pas mélanger transactionnel critique et marketing risqué.

16. Dépannage

Le port 25 sortant est bloqué

timeout 7 bash -lc '</dev/tcp/gmail-smtp-in.l.google.com/25'

Correction : demander l’ouverture au provider ou choisir un provider compatible email server.

Gmail refuse avec DMARC

550-5.7.26 Unauthenticated email from domain is not accepted due to DMARC policy

• vérifier SPF ;
• vérifier DKIM ;
• mettre DMARC temporairement en p=none ou p=quarantine selon contexte ;
• supprimer les anciens SPF contradictoires ;
• relancer doctor.

DKIM absent

Après création du domaine dans Mailcow, générer la clé DKIM dans l’interface, puis coller le TXT dans la zone DNS. Ensuite attendre la propagation et relancer :

python3 mailcow_assisted_installer_v3.py doctor \
  --domain example.com \
  --hostname mail.example.com \
  --public-ip 1.2.3.4

PTR incorrect

• vérifier dig -x IP ;
• corriger le reverse DNS côté provider ;
• le PTR doit pointer vers mail.example.com ;
• le A record de mail.example.com doit revenir vers l’IP.

Ancien MX encore actif

Si Google Workspace, Zoho ou Microsoft 365 restent dans les MX, une partie des emails partira ailleurs.

dig MX example.com +short

Cloudflare proxy activé par erreur

Pour un hostname mail, le record doit être en DNS only. Le proxy orange Cloudflare ne doit pas être utilisé pour SMTP/IMAP.

Docker déjà installé par le provider

Si des paquets Docker conflictuels existent, utiliser --remove-conflicting-docker uniquement sur un serveur neuf ou validé.

sudo python3 mailcow_assisted_installer_v3.py all \
  --domain example.com \
  --hostname mail.example.com \
  --public-ip 1.2.3.4 \
  --remove-conflicting-docker \
  --yes

17. Utilisation dans une offre commerciale

L’outil est surtout intéressant s’il est intégré dans une offre packagée. Le client ne paie pas uniquement l’installation d’un serveur : il paie un résultat maîtrisé, des livrables, une procédure de validation et un accompagnement pendant la phase sensible.

Offres possibles

Argumentaire client

Livrables à remettre au client

• rapport d’audit initial ;
• plan DNS ;
• preuve PTR/rDNS ;
• snippet Django ou applicatif ;
• plan warm-up ;
• runbook exploitation ;
• checklist de bascule ;
• rapport final readiness score ;
• ZIP delivery pack généré par la V3.

Limites à écrire dans le contrat