Configurer l'envoi d'e-mails (SMTP)

À qui s'adresse cette page

Administrateurs qui souhaitent activer l'envoi d'e-mails (validation de compte, réinitialisation de mot de passe, notifications). Sans configuration SMTP, gitrust démarre normalement mais toutes les fonctionnalités e-mail sont désactivées.

Variables concernées

Toutes ces variables se placent dans /opt/gitrust/.env (ou dans l'EnvironmentFile de votre service systemd / docker-compose.yml). Un redémarrage du service est nécessaire après modification.

Variable Obligatoire Défaut Description
SMTP_HOST Oui — Nom d'hôte ou IP du serveur SMTP
SMTP_PORT Non 587 Port SMTP (25, 465, 587, 1025)
SMTP_USER Non — Identifiant SMTP (souvent = adresse e-mail)
SMTP_PASSWORD Non — Mot de passe applicatif SMTP
SMTP_FROM Non — Adresse expéditeur visible (doit être valide)
SMTP_FROM_NAME Non — Nom affiché dans le champ « De : »
SMTP_USE_TLS Non true Activer TLS natif (port 465)
SMTP_USE_STARTTLS Non true Activer STARTTLS (port 587)
SMTP_ACCEPT_INVALID_CERTS Non false Accepter les certificats invalides (dev seulement)
SMTP_CA_CERT_PATH Non — Chemin vers un CA personnalisé (PEM)
EMAIL_BASE_URL Oui (prod) http://localhost:3000 URL de base pour les liens dans les e-mails
EMAIL_VALIDATION_REQUIRED Non true Exiger la validation e-mail à l'inscription
EMAIL_QUEUE_BATCH_SIZE Non 10 Nombre d'e-mails traités par tick
EMAIL_QUEUE_RETRY_ATTEMPTS Non 5 Nombre de tentatives avant abandon
EMAIL_QUEUE_RETRY_DELAY_SECONDS Non 300 Délai entre deux tentatives (secondes)

Important : Ne jamais activer SMTP_ACCEPT_INVALID_CERTS=true en production — cela ouvre la voie à des attaques MITM sur tous les e-mails sortants.

Recettes par prestataire

Gmail (compte personnel ou Google Workspace)

Google exige un mot de passe applicatif (pas votre mot de passe Google). Générez-le sur myaccount.google.com/apppasswords en activant au préalable la validation en deux étapes.

SMTP_HOST=smtp.gmail.com
SMTP_PORT=587
SMTP_USER=votre.adresse@gmail.com
SMTP_PASSWORD=xxxx_xxxx_xxxx_xxxx   # mot de passe applicatif (16 caractères)
SMTP_FROM=votre.adresse@gmail.com
SMTP_FROM_NAME=Gitrust
SMTP_USE_TLS=false
SMTP_USE_STARTTLS=true
EMAIL_BASE_URL=https://VOTRE_DOMAINE

Limite : Gmail impose un quota de 500 e-mails/jour pour les comptes personnels. Pour les volumes importants, utilisez un service dédié (SendGrid, Brevo, etc.).

OVH / Infomaniak / Gandi

Ces hébergeurs utilisent STARTTLS sur le port 587 ou SMTPS sur le port 465.

# OVH (SSL/TLS natif sur 465)
SMTP_HOST=ssl0.ovh.net
SMTP_PORT=465
SMTP_USER=noreply@VOTRE_DOMAINE.com
SMTP_PASSWORD=MOT_DE_PASSE_EMAIL
SMTP_FROM=noreply@VOTRE_DOMAINE.com
SMTP_FROM_NAME=Gitrust
SMTP_USE_TLS=true
SMTP_USE_STARTTLS=false
EMAIL_BASE_URL=https://VOTRE_DOMAINE

# Gandi (STARTTLS sur 587)
SMTP_HOST=mail.gandi.net
SMTP_PORT=587
SMTP_USER=noreply@VOTRE_DOMAINE.com
SMTP_PASSWORD=MOT_DE_PASSE_EMAIL
SMTP_FROM=noreply@VOTRE_DOMAINE.com
SMTP_FROM_NAME=Gitrust
SMTP_USE_TLS=false
SMTP_USE_STARTTLS=true
EMAIL_BASE_URL=https://VOTRE_DOMAINE

Postfix local (instance interne sans authentification)

Pour les déploiements sur réseau interne où Postfix est installé sur le même serveur :

SMTP_HOST=127.0.0.1
SMTP_PORT=25
# Pas de SMTP_USER ni SMTP_PASSWORD si Postfix accepte sans auth sur loopback
SMTP_FROM=noreply@VOTRE_DOMAINE.com
SMTP_FROM_NAME=Gitrust
SMTP_USE_TLS=false
SMTP_USE_STARTTLS=false
EMAIL_BASE_URL=https://VOTRE_DOMAINE

Vérifiez que Postfix accepte les connexions depuis 127.0.0.1 :

# Dans /etc/postfix/main.cf
mynetworks = 127.0.0.0/8

Mailpit / Mailhog (développement local)

SMTP_HOST=localhost
SMTP_PORT=1025
SMTP_FROM=dev@localhost
SMTP_FROM_NAME=Gitrust-Dev
SMTP_USE_TLS=false
SMTP_USE_STARTTLS=false
SMTP_ACCEPT_INVALID_CERTS=false
EMAIL_BASE_URL=http://localhost:4000
EMAIL_VALIDATION_REQUIRED=false

Démarrez Mailpit : docker run -p 1025:1025 -p 8025:8025 axllent/mailpit
Interface web : http://localhost:8025

Tester la configuration

Après avoir modifié le .env et redémarré gitrust, testez via le panel admin :

  1. Connectez-vous à /admin
  2. Accédez à /admin/email
  3. Saisissez une adresse de test et cliquez Envoyer un e-mail de test

Panel de test SMTP

En cas d'erreur, consultez les logs :

sudo journalctl -u gitrust -n 50 --no-pager | grep -i "smtp\|email\|mail"

Erreurs courantes :

Message dans les logs Cause Correction
Connection refused sur le port SMTP SMTP_HOST ou SMTP_PORT incorrect Vérifier les paramètres du prestataire
Authentication failed SMTP_USER ou SMTP_PASSWORD incorrect Pour Gmail : utiliser un mot de passe applicatif, pas le mot de passe du compte
Certificate verification failed Certificat TLS du serveur SMTP invalide ou CA non reconnu Spécifier SMTP_CA_CERT_PATH ou contacter le prestataire
EMAIL_BASE_URL pointe vers localhost Liens dans les e-mails non cliquables pour les destinataires externes Définir EMAIL_BASE_URL=https://VOTRE_DOMAINE

Pour aller plus loin