Aller au contenu

Auto-hébergement

Installation auto-hébergée

Comment auto-héberger Notifuse

Astuce

Vous cherchez une solution gérée ? Notifuse Cloud s’occupe de l’hébergement, de la sécurité, des sauvegardes, des mises à jour et de la maintenance, à partir de 16 $/mois.

Premiers pas

Notifuse comprend un assistant d’installation interactif. Beaucoup de variables d’environnement sont facultatives et peuvent être renseignées dans l’interface web au premier lancement.

L'assistant d'installation rempli : administrateur, envoi des emails système (SMTP), mises à jour et télémétrie, authentification unique et passerelle SMTP, avec à côté ce qui reste à remplir

Démarrage rapide avec l’assistant d’installation

  1. Déployez Notifuse avec l’une des options ci-dessous
  2. Ouvrez votre instance dans un navigateur web
  3. Remplissez l’assistant d’installation :
    • Saisissez l’email de l’administrateur root (un ou plusieurs)
    • Vérifiez l’endpoint de l’API, prérempli avec l’adresse de la page
    • Configurez le serveur SMTP qui envoie les codes de connexion et les invitations, et testez la connexion
    • Gardez ou désactivez la vérification des mises à jour et la télémétrie anonyme (toutes deux activées par défaut)
    • Si vous le souhaitez, configurez l’authentification unique (OpenID Connect) et la passerelle SMTP
  4. Commencez à utiliser Notifuse.

Un réglage déjà fourni par une variable d’environnement apparaît verrouillé dans l’assistant, avec le nom de la variable. L’assistant ne le demande pas.

compose.yaml lance Notifuse avec son propre PostgreSQL 18. Le fichier se suffit à lui-même : un serveur n’a pas besoin d’un clone du dépôt, seulement de Docker Engine 25.0 et de Compose v2.24 ou plus récent (docker compose version).

Attention

Ces étapes créent une nouvelle installation. Pour mettre à jour une installation en service, gardez son .env et la SECRET_KEY qu’il contient : une nouvelle clé seule rend illisibles vos données enregistrées (voir Mettre à jour). Une installation démarrée depuis compose.yaml avant la version 42.0 sans définir SECRET_KEY tourne avec une valeur par défaut que Notifuse refuse désormais : Remplacer la clé secrète donne cette valeur et la modification à faire.

mkdir notifuse && cd notifuse
curl -fsSL https://raw.githubusercontent.com/Notifuse/notifuse/main/compose.yaml -o compose.yaml

# Generate the secret key and the database password once, and keep them:
# the key encrypts your stored data. An existing .env is left alone.
test -e .env || cat > .env <<EOF
SECRET_KEY=$(openssl rand -base64 32)
DB_PASSWORD=$(openssl rand -hex 24)
EOF

docker compose up -d

Notifuse démarre alors sur le port 8081, avec un PostgreSQL joignable depuis le serveur lui-même uniquement (127.0.0.1:5433). Au premier lancement, l’assistant d’installation vous guide dans la configuration. Vous pouvez aussi définir des variables d’environnement dans le fichier .env : chaque variable qu’il contient est transmise à Notifuse.

Notifuse sert du HTTP simple. Placez devant lui un reverse proxy avec TLS avant d’y faire pointer un domaine, et mettez HTTP_BIND=127.0.0.1 dans .env quand ce proxy tourne sur le même serveur.

Attention

Compose nomme le volume de la base d’après le dossier qui contient compose.yaml (ici notifuse_postgres-data). Gardez ce nom de dossier : dans un dossier renommé ou déplacé, docker compose up -d démarre une nouvelle installation sur une base vide. docker compose down -v supprime la base de données.

Mettre à jour une installation Docker Compose

Lisez les entrées du changelog entre votre version et la nouvelle, faites une sauvegarde, puis téléchargez le compose.yaml de la nouvelle version par-dessus le vôtre (ou mettez NOTIFUSE_VERSION=v44.0 dans .env pour choisir la version) et lancez docker compose up -d.

La version 44.0 fait passer compose.yaml à PostgreSQL 18 : le premier docker compose up -d copie vos données PostgreSQL 17 dans un second volume, puis les met à niveau. Mettre à niveau PostgreSQL explique ce qui se passe, comment le vérifier et comment revenir en arrière.

Depuis un clone du dépôt

Dans un clone, le même fichier compile Notifuse depuis les sources : docker compose up -d --build, ou docker compose watch pour recompiler à chaque modification. Sans --build, il lance l’image publiée pour la version indiquée dans le fichier. Une version pas encore publiée, sur la branche dev, est compilée depuis le checkout. Jusqu’à la version 43, compose.yaml compilait toujours depuis le checkout.

Option 2 : Docker seul (production)

Pour un déploiement en production, utilisez l’image Docker seule avec votre propre base PostgreSQL :

# Generate SECRET_KEY once with: openssl rand -base64 32, and keep it: it encrypts your stored data
docker run -d --name notifuse -p 8080:8080 \
  -e SECRET_KEY=<your secret key> \
  notifuse/notifuse:latest

Au premier lancement, l’assistant d’installation vous guide dans la configuration. Vous pouvez aussi définir des variables d’environnement.

Base de données PostgreSQL (option 2 uniquement)

Avec l’option Docker seul, vous pouvez utiliser n’importe quelle base PostgreSQL avec des identifiants root. Notifuse crée sa propre base système.

Version : PostgreSQL 17 ou plus récent (Notifuse refuse de démarrer sur un serveur plus ancien). compose.yaml fournit PostgreSQL 18

Notifuse crée une base de données par espace de travail pour éviter les problèmes liés au multi-tenant, d’où le besoin d’identifiants root.

Remarque : Docker Compose inclut PostgreSQL, ce point ne s’y applique donc pas.

Un serveur SMTP

Notifuse a besoin d’un serveur SMTP pour envoyer les emails système, comme les codes de connexion et les emails d’invitation.

Avec SES, vous pouvez créer des identifiants SMTP dans la section des réglages SMTP du tableau de bord SES.

Un endpoint d’API public

Notifuse a besoin d’un endpoint d’API public, joignable depuis le web, par exemple https://emails.yourcompany.com.

Derrière un reverse proxy, transmettez à Notifuse l’en-tête Host d’origine, ou mettez-le dans X-Forwarded-Host. Les versions web des emails ne s’ouvrent que sur le domaine avec lequel leur lien a été envoyé et sur API_ENDPOINT. Un proxy qui remplace Host par son adresse amont, sans définir X-Forwarded-Host, rend toutes les versions web indisponibles. Un proxy qui le remplace par l’hôte de API_ENDPOINT permet à chaque domaine personnalisé d’afficher les versions web de tous les espaces de travail.

Variables d’environnement

Avec l’assistant d’installation, beaucoup de variables d’environnement sont facultatives et peuvent être renseignées dans l’interface web. Une variable d’environnement définie l’emporte toujours sur le réglage enregistré en base.

Attention

Caractères spéciaux dans les fichiers .env

Dans un fichier .env, une valeur qui contient le caractère # (fréquent dans les mots de passe) doit être entourée de guillemets :

# ✅ CORRECT - value is quoted
DB_PASSWORD="mypass#word123"
SMTP_PASSWORD="smtp#pass456"

# ❌ INCORRECT - will be truncated at the # character
DB_PASSWORD=mypass#word123   # parsed as "mypass"
SMTP_PASSWORD=smtp#pass456   # parsed as "smtp"

Cela ne concerne que les fichiers .env, pas les variables définies directement dans votre shell, dans Docker Compose ou dans une plateforme d’orchestration de conteneurs.

Variables obligatoires

VariableDescription
DB_HOSTHôte PostgreSQL (par exemple localhost ou db.yourcompany.com)
DB_PORTPort PostgreSQL (par exemple 5432)
DB_USERNom d’utilisateur de la base (par exemple postgres)
DB_PASSWORDMot de passe de la base (par exemple postgres)
SECRET_KEYClé secrète de chiffrement et de signature (à générer avec la commande ci-dessous)

Générer SECRET_KEY :

openssl rand -base64 32

Notifuse refuse de démarrer avec une SECRET_KEY qui donne moins de 32 octets.

Attention

Ne remplacez jamais votre SECRET_KEY par une nouvelle valeur seule. Elle chiffre tous les secrets des intégrations des espaces de travail (clés API des fournisseurs d’email, mots de passe SMTP, etc.), qu’une nouvelle clé seule ne peut pas lire. Pour la changer, suivez Remplacer la clé secrète.

Remplacer la clé secrète

SECRET_KEY peut contenir plusieurs clés séparées par des virgules (une virgule qui fait partie d’une clé s’écrit deux fois). La première clé chiffre et signe. Les autres servent seulement à lire les données enregistrées avec elles. Quand Notifuse démarre avec une liste, il rechiffre ces données avec la première clé, en une seule transaction, avant de servir quoi que ce soit. Pour remplacer votre clé :

  1. Générez une nouvelle clé avec openssl rand -base64 32.
  2. Placez-la en premier, suivie de votre clé actuelle : SECRET_KEY=<new key>,<current key>. Si votre clé actuelle contient une virgule, écrivez cette virgule deux fois. Si elle commence ou finit par une virgule, mettez une espace entre elle et la virgule qui sépare les clés (SECRET_KEY=<new key>, ,,<rest of the key>). Une version antérieure à 42.0 lit toute la liste comme une seule clé : lors du passage à 42.0, définissez la liste dans la même étape.
  3. Arrêtez toutes les instances de Notifuse, puis démarrez-les toutes avec cette valeur. Une instance qui tourne encore avec la clé actuelle seule ne peut pas lire les données que les autres ont rechiffrées, et une instance qui tourne avec la liste ne peut pas lire ce qu’écrit une telle instance avant le prochain démarrage avec la liste.
  4. Une fois toutes les instances lancées avec cette valeur, donnez à SECRET_KEY la nouvelle clé seule, sans guillemets ni espaces autour : une clé seule est utilisée exactement telle qu’elle est écrite. Si elle n’ouvre aucun des espaces de travail enregistrés (ou, tant qu’il n’y en a aucun, aucun des réglages système chiffrés), Notifuse ne démarre pas.

Si la clé d’un espace de travail, ou un identifiant qu’il utilise, ne s’ouvre avec aucune des clés listées, Notifuse ne démarre pas, ne modifie rien et nomme cet espace de travail. Un réglage système chiffré qu’aucune d’elles n’ouvre (un identifiant SMTP ou le client secret OIDC enregistrés dans l’assistant d’installation, le certificat TLS ou la clé de la passerelle SMTP) est laissé tel quel et nommé dans un avertissement des logs de démarrage, et Notifuse tourne sans lui : pour le garder, listez la clé qui le chiffre. Notifuse ne démarre pas, et nomme le réglage, quand l’authentification unique ou la passerelle SMTP est activée et en a besoin, ou quand aucun espace de travail n’est encore enregistré et qu’aucun de ces réglages ne s’ouvre.

Remplacer la clé déconnecte tout le monde. Les clés API doivent être supprimées puis recréées, les invitations en attente renvoyées, et les scripts qui appellent user.rootSignin signent avec la nouvelle clé. Un client API qui enregistre une intégration avec les identifiants chiffrés lus avant le changement est refusé tant qu’il n’a pas relu l’espace de travail. Les sauvegardes de base faites avant le changement ont toujours besoin de l’ancienne clé. Les données conservées dans la base de chaque espace de travail, comme l’historique des messages, sont chiffrées avec la clé propre à cet espace et ne sont pas touchées.

Attention

Avant la version 42.0, compose.yaml fournissait une SECRET_KEY par défaut et env.example une valeur d’exemple. Notifuse refuse de démarrer quand la première clé de SECRET_KEY est l’une de ces valeurs ou donne moins de 32 octets, et lit une virgule simple comme un séparateur de clés : si votre clé contient une virgule, écrivez chacune de ses virgules deux fois lors de la mise à jour. Si votre installation tourne avec l’une de ces valeurs, remplacez-la comme ci-dessus, en la gardant après la nouvelle clé, dans la même étape que le passage à 42.0. Si vous avez démarré depuis compose.yaml sans définir SECRET_KEY, votre clé actuelle est l’ancienne valeur par défaut :

# Put the output of openssl rand -base64 32 before the comma
SECRET_KEY=<new key>,d04zCk3Fa45oOjDWHpAvc1AZxnLdGffOnNWK+Jt2yXf37+FTfuMMHb8flcfPMqLluRR3rvhbr555r6j1DEigrA==

Variables de l’application (facultatives avec l’assistant d’installation)

Renseignez-les dans l’assistant d’installation au premier lancement, ou en variables d’environnement, qui l’emportent toujours sur l’assistant.

VariableDescription
ROOT_EMAILEmail de l’administrateur root (par exemple admin@yourcompany.com). Accepte plusieurs emails séparés par des virgules ou des points-virgules pour donner les droits root à plusieurs administrateurs (par exemple alice@yourcompany.com,bob@yourcompany.com). La comparaison tient compte de la casse.
API_ENDPOINTURL publique de l’endpoint de l’API (par exemple https://emails.yourcompany.com). Pour passer plus tard à un autre domaine, voir Changer de domaine.
SMTP_HOSTHôte du serveur SMTP (par exemple smtp.gmail.com)
SMTP_PORTPort du serveur SMTP (par exemple 587 ou 465)
SMTP_USERNAMENom d’utilisateur SMTP (par exemple noreply@yourcompany.com)
SMTP_PASSWORDMot de passe SMTP (par exemple your_smtp_password)
SMTP_FROM_EMAILAdresse d’expédition (par exemple noreply@yourcompany.com)
SMTP_FROM_NAMENom d’expéditeur (par exemple Your Company Name)
SMTP_EHLO_HOSTNAMENom d’hôte EHLO personnalisé pour les connexions SMTP (par exemple mail.yourdomain.com). Vide, il prend la valeur de l’hôte SMTP. Utile quand des serveurs SMTP rejettent EHLO localhost.

Note

Plusieurs utilisateurs root : ROOT_EMAIL peut contenir plusieurs emails (séparés par des virgules ou des points-virgules). Une instance partagée peut ainsi avoir plusieurs administrateurs avec les droits root : créer des espaces de travail, accéder aux paramètres système et s’authentifier par programme. Au démarrage, Notifuse crée un compte utilisateur pour chaque email listé, si bien que chaque root peut se connecter tout de suite. La comparaison tient compte de la casse, et un email unique fonctionne exactement comme avant. L’assistant d’installation définit le premier root (le principal). Ajoutez-en d’autres sous forme de liste dans l’assistant ou avec la variable d’environnement ROOT_EMAIL.

Variables facultatives

VariableDescriptionPar défaut
Configuration du serveur
SERVER_PORTPort d’écoute du serveur (par exemple 8080)8080
SERVER_HOSTAdresse d’hôte à laquelle se lier (par exemple 0.0.0.0)0.0.0.0
CORS_ALLOW_ORIGINOrigines autorisées à appeler l’API depuis un navigateur : *, une origine, ou une liste séparée par des virgules (par exemple https://yourapp.com,https://admin.yourapp.com ; les listes demandent la version 41.1 ou plus récente). Une valeur restreinte doit inclure chaque domaine personnalisé d’espace de travail, dont la console et le centre de notifications appellent l’API depuis leur propre origine.*
ENVIRONMENTMode d’environnement (par exemple production)production
LOG_LEVELNiveau de log (par exemple debug ou warn)info
Configuration de la base de données
DB_PREFIXPréfixe du nom des bases système et d’espace de travail (par exemple notifuse pour notifuse_system et notifuse_ws_*)notifuse
DB_NAMENom de la base (par exemple notifuse_system)${DB_PREFIX}_system
DB_SSLMODEMode SSL de la base (par exemple require ou disable)require
DB_EXPECT_EXISTINGtrue interdit de créer ou d’initialiser la base système, et de créer une base d’espace de travail manquante. Définissez-la sur un serveur qui doit déjà contenir les données (une mise à jour, une restauration) : un PostgreSQL vide arrête alors Notifuse au lieu de démarrer une nouvelle installationfalse
DB_MAX_CONNECTIONSNombre maximal de connexions, toutes bases confondues (par exemple 100)100
DB_MAX_CONNECTIONS_PER_DBNombre maximal de connexions par base d’espace de travail (par exemple 3)3
DB_CONNECTION_MAX_LIFETIMEDurée de vie maximale d’une connexion (par exemple 10m)10m
DB_CONNECTION_MAX_IDLE_TIMEDurée d’inactivité maximale avant la fermeture d’une connexion (par exemple 5m)5m
Configuration du planificateur de tâches
TASK_SCHEDULER_ENABLEDActive le planificateur de tâches interne (par exemple true ou false)true
TASK_SCHEDULER_INTERVALIntervalle d’exécution des tâches, en secondes (par exemple 30)30
TASK_SCHEDULER_MAX_TASKSNombre maximal de tâches simultanées (par exemple 10)10
Configuration des newsletters
BROADCAST_DATA_FEED_ALLOW_PRIVATE_HOSTSAutorise les data feeds des newsletters à récupérer des données depuis des adresses privées, de loopback et link-local. Cela désactive la protection SSRF pour les requêtes de data feed : ne l’activez que dans des déploiements de confiance qui récupèrent volontairement des flux sur votre réseau interne (par exemple true).false
EMAIL_QUEUE_CONCURRENCYNombre d’emails que chaque intégration d’email autre que SMTP envoie en même temps pour les newsletters et les automations, par instance de Notifuse, entre 1 et 50 (par exemple 20 ; version 42.0 ou plus récente). Voir Vitesse d’envoi.10
EMAIL_QUEUE_SMTP_CONCURRENCYLa même chose pour les intégrations SMTP, entre 1 et 50 (version 42.0 ou plus récente). Ne l’augmentez que si votre serveur SMTP accepte plusieurs connexions simultanées (par exemple 4).1
Configuration des webhooks
WEBHOOK_DELIVERY_ALLOW_PRIVATE_HOSTSAutorise les webhooks sortants (abonnements webhook et nœuds webhook des automations) à joindre des adresses privées, de loopback et link-local. Cela désactive la protection SSRF pour eux : ne l’activez que dans des déploiements de confiance qui envoient volontairement des webhooks sur votre réseau interne, comme n8n sur le même réseau Docker (par exemple true). Tant qu’elle est désactivée, les webhooks sortants se connectent directement et ignorent HTTP_PROXY/HTTPS_PROXY.false
Licence
NOTIFUSE_LICENSE_KEYUne clé de licence auto-hébergée. L’emporte sur une clé collée dans la console. Inutile pour faire tourner Notifuse.-
Confidentialité
TELEMETRYEnvoie des statistiques d’utilisation anonymes (par exemple true ou false)true
CHECK_FOR_UPDATESVérifie la disponibilité de nouvelles versions (par exemple true ou false)true
Configuration de la passerelle SMTP
SMTP_BRIDGE_ENABLEDActive le serveur de passerelle SMTP pour les emails transactionnels (par exemple true ou false)false
SMTP_BRIDGE_PORTPort de la passerelle SMTP (par exemple 587 pour STARTTLS, 465 pour le TLS implicite)587
SMTP_BRIDGE_DOMAINNom de domaine public de la passerelle SMTP (par exemple smtp.yourdomain.com)localhost
SMTP_BRIDGE_TLSMode TLS : starttls, implicit ou off (voir plus bas). Déterminé automatiquement s’il n’est pas défini.auto
SMTP_BRIDGE_TLS_CERT_BASE64Certificat TLS encodé en base64 (requis pour starttls et implicit)-
SMTP_BRIDGE_TLS_KEY_BASE64Clé privée TLS encodée en base64 (requise pour starttls et implicit)-
Authentification unique (OIDC) (voir le guide SSO)
OIDC_ENABLEDActive l’authentification unique via OpenID Connect (par exemple true ou false)false
OIDC_ISSUER_URLURL de l’émetteur de l’IdP, obligatoirement en https (par exemple https://accounts.google.com)-
OIDC_CLIENT_IDClient ID OAuth2 fourni par votre fournisseur d’identité-
OIDC_CLIENT_SECRETClient secret OAuth2 (chiffré au repos, jamais envoyé au navigateur)-
OIDC_REDIRECT_URIURL de callback enregistrée chez l’IdP. Dérivée de API_ENDPOINT si elle est vide.<API_ENDPOINT>/api/user.oidc.callback
OIDC_SCOPESScopes séparés par des espaces (openid toujours inclus)openid email profile
OIDC_BUTTON_LABELLibellé du bouton de connexionSign in with SSO
OIDC_AUTO_CREATE_USERSCrée automatiquement les comptes à la première connexion SSO (demande OIDC_ALLOWED_DOMAINS)false
OIDC_ALLOWED_DOMAINSListe des domaines d’email autorisés pour la création automatique, séparés par des virgules ou des points-virgules-
Configuration du tracing
TRACING_ENABLEDActive le tracing (par exemple true)false
TRACING_SERVICE_NAMENom du service pour le tracing (par exemple notifuse-production)notifuse-api
TRACING_SAMPLING_PROBABILITYProbabilité d’échantillonnage (par exemple 0.05)0.1
TRACING_TRACE_EXPORTERExportateur de traces : jaeger/zipkin/stackdriver/datadog/xray/none (par exemple jaeger ou datadog)none
TRACING_JAEGER_ENDPOINTEndpoint Jaeger (par exemple http://jaeger:14268/api/traces)http://localhost:14268/api/traces
TRACING_ZIPKIN_ENDPOINTEndpoint Zipkin (par exemple http://zipkin:9411/api/v2/spans)http://localhost:9411/api/v2/spans
TRACING_STACKDRIVER_PROJECT_IDID de projet Stackdriver (par exemple my-gcp-project-id)-
TRACING_AZURE_INSTRUMENTATION_KEYClé d’instrumentation Azure Monitor (par exemple 12345678-1234-1234-1234-123456789012)-
TRACING_DATADOG_AGENT_ADDRESSAdresse de l’agent Datadog (par exemple datadog-agent:8126)localhost:8126
TRACING_DATADOG_API_KEYClé API Datadog (par exemple 1234567890abcdef1234567890abcdef)-
TRACING_XRAY_REGIONRégion AWS X-Ray (par exemple us-east-1)us-west-2
TRACING_AGENT_ENDPOINTEndpoint d’agent générique (par exemple monitoring-agent:8126)localhost:8126
TRACING_METRICS_EXPORTERExportateur de métriques : stackdriver/prometheus/datadog/none (par exemple prometheus)none
TRACING_PROMETHEUS_PORTPort des métriques Prometheus (par exemple 9464)9464

Configuration de la passerelle SMTP

La passerelle SMTP relie à Notifuse les applications SaaS qui ne proposent qu’une intégration SMTP (comme Supabase Auth, Firebase ou Auth0) : leurs emails utilisent alors les designs et l’identité visuelle que vous construisez dans l’éditeur MJML de Notifuse, à la place des modèles par défaut du SaaS.

Voir la documentation d’utilisation de la passerelle SMTP pour des exemples d’envoi une fois la configuration faite.

Modes TLS

La passerelle prend en charge trois modes TLS via SMTP_BRIDGE_TLS :

ModeDescriptionPort habituel
starttlsÉcoute en clair. Les clients doivent passer en TLS via STARTTLS avant AUTH. Mode par défaut quand des certificats sont fournis.587
implicitTLS dès le premier octet (SMTPS). Requis pour les clients qui ne parlent que le TLS implicite.465
offPas de TLS. Sûr uniquement derrière un reverse proxy qui termine le TLS (HAProxy, Caddy layer4, stunnel, nginx Mail, Postfix) sur un réseau de confiance.tous

Quand SMTP_BRIDGE_TLS n’est pas défini, Notifuse choisit starttls si le certificat et la clé sont tous deux fournis, sinon off en développement.

Attention

En production (ENVIRONMENT=production), la passerelle refuse de démarrer sans TLS configuré. Fournissez SMTP_BRIDGE_TLS_CERT_BASE64 et SMTP_BRIDGE_TLS_KEY_BASE64, ou définissez explicitement SMTP_BRIDGE_TLS=off si vous êtes derrière un reverse proxy qui termine le TLS.

Configuration de production avec Let’s Encrypt

En production, utilisez des certificats TLS valides de Let’s Encrypt, obtenus avec certbot et un challenge DNS.

Étape 1 : installer Certbot

# Ubuntu/Debian
sudo apt-get update
sudo apt-get install certbot

# macOS
brew install certbot

# CentOS/RHEL
sudo yum install certbot

Étape 2 : générer le certificat avec un challenge DNS

Le challenge DNS est recommandé : il n’a pas besoin des ports 80 ou 443 ouverts, et fonctionne même si votre serveur SMTP est sur un autre port.

# Generate certificate using DNS challenge
sudo certbot certonly \
  --manual \
  --preferred-challenges dns \
  --email admin@yourdomain.com \
  --agree-tos \
  -d smtp.yourdomain.com

Certbot vous demande alors de créer un enregistrement DNS TXT :

Please deploy a DNS TXT record under the name
_acme-challenge.smtp.yourdomain.com with the following value:

XyZ123AbC456...

Before continuing, verify the record is deployed by running:
dig -t txt _acme-challenge.smtp.yourdomain.com

Étape 3 : ajouter l’enregistrement DNS TXT

Ajoutez l’enregistrement TXT chez votre fournisseur DNS :

Type: TXT
Name: _acme-challenge.smtp
Value: XyZ123AbC456... (the value provided by certbot)
TTL: 300 (5 minutes)

Attendez quelques minutes que le DNS se propage, puis vérifiez l’enregistrement :

dig -t txt _acme-challenge.smtp.yourdomain.com

# Or using nslookup
nslookup -type=TXT _acme-challenge.smtp.yourdomain.com

Une fois l’enregistrement vérifié, appuyez sur Entrée dans certbot pour continuer.

Étape 4 : encoder les certificats en base64

Une fois les certificats générés par certbot, encodez-les en base64 :

# Certificate location (typically):
# Certificate: /etc/letsencrypt/live/smtp.yourdomain.com/fullchain.pem
# Private Key: /etc/letsencrypt/live/smtp.yourdomain.com/privkey.pem

# Encode certificate to base64 (single line)
sudo cat /etc/letsencrypt/live/smtp.yourdomain.com/fullchain.pem | base64 -w 0 > cert_base64.txt

# Encode private key to base64 (single line)
sudo cat /etc/letsencrypt/live/smtp.yourdomain.com/privkey.pem | base64 -w 0 > key_base64.txt

# On macOS, omit the -w flag:
sudo cat /etc/letsencrypt/live/smtp.yourdomain.com/fullchain.pem | base64 > cert_base64.txt
sudo cat /etc/letsencrypt/live/smtp.yourdomain.com/privkey.pem | base64 > key_base64.txt

Étape 5 : ajouter aux variables d’environnement

Copiez les valeurs encodées en base64 dans votre fichier .env :

SMTP_BRIDGE_ENABLED=true
SMTP_BRIDGE_DOMAIN=smtp.yourdomain.com
SMTP_BRIDGE_PORT=587
SMTP_BRIDGE_TLS=starttls
SMTP_BRIDGE_TLS_CERT_BASE64="<paste-cert-base64-here>"
SMTP_BRIDGE_TLS_KEY_BASE64="<paste-key-base64-here>"

Note

Certbot met en place une tâche cron de renouvellement. Après chaque renouvellement, réencodez les certificats en base64 et mettez à jour vos variables d’environnement.

Configuration de développement avec des certificats auto-signés

En développement local, vous pouvez utiliser des certificats auto-signés :

# Using the provided script
./scripts/generate-dev-certs.sh localapi.notifuse.com

# Or manually with openssl
openssl req -x509 -newkey rsa:2048 \
  -keyout dev-cert.key.pem \
  -out dev-cert.cert.pem \
  -days 365 -nodes \
  -subj "/CN=localhost" \
  -addext "subjectAltName=DNS:localhost,IP:127.0.0.1"

# Encode to base64
cat dev-cert.cert.pem | base64 > cert_base64.txt
cat dev-cert.key.pem | base64 > key_base64.txt

Attention : les certificats auto-signés sont réservés au développement. Ne les utilisez jamais en production.

Gestion de la configuration

L’assistant d’installation convient aux déploiements rapides et aux tests : il enregistre la configuration de façon sécurisée dans la base de données, et vous la gérez dans l’interface web. En production, les variables d’environnement sont recommandées : elles protègent mieux les données sensibles et laissent votre pipeline de déploiement gérer la configuration. Quand les deux sont définis, la variable d’environnement l’emporte toujours.

En production, nous recommandons les variables d’environnement pour la configuration sensible (identifiants SMTP, SECRET_KEY) et l’assistant d’installation ou l’interface d’administration pour le reste (endpoint de l’API, etc.).

Authentification par programme

Pour les pipelines CI/CD et les déploiements automatisés, un utilisateur root peut s’authentifier par programme avec une signature HMAC-SHA256 au lieu d’un lien magique. Quand ROOT_EMAIL liste plusieurs adresses, utilisez l’une d’elles comme ROOT_EMAIL ci-dessous : l’email signé doit correspondre exactement à l’un des emails root configurés.

#!/bin/bash
# Configuration
NOTIFUSE_URL="https://your-notifuse-instance.com"
SECRET_KEY="your-secret-key"  # the first key when SECRET_KEY lists several
ROOT_EMAIL="admin@example.com"
TIMESTAMP=$(date +%s)

# Generate HMAC signature
MESSAGE="${ROOT_EMAIL}:${TIMESTAMP}"
SIGNATURE=$(echo -n "$MESSAGE" | openssl dgst -sha256 -hmac "$SECRET_KEY" | awk '{print $2}')

# Authenticate and get JWT token
curl -X POST "${NOTIFUSE_URL}/api/user.rootSignin" \
  -H "Content-Type: application/json" \
  -d "{\"email\":\"${ROOT_EMAIL}\",\"timestamp\":${TIMESTAMP},\"signature\":\"${SIGNATURE}\"}"

L’endpoint renvoie un token JWT pour les requêtes API suivantes. Le timestamp doit être à moins de 60 secondes de l’heure du serveur, et les requêtes sont limitées à 5 tentatives toutes les 5 minutes.

Plateformes d’hébergement tierces

Notifuse est aussi disponible sur les plateformes tierces suivantes.

Attention

Ces plateformes ne sont pas prises en charge officiellement et font souvent tourner des versions obsolètes de Notifuse. Pour la dernière version, les mises à jour automatiques et le support officiel, utilisez Notifuse Cloud.