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 :

Connectez-vous à /admin
Accédez à /admin/email
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`

Eric / documentation