> ## Documentation Index
> Fetch the complete documentation index at: https://www.notifuse.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Installation auto-hébergée

> Comment auto-héberger Notifuse

> [!TIP]
>
> **Vous cherchez une solution gérée ?** [Notifuse Cloud](https://cloud.notifuse.com) 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](https://www.notifuse.com/docs/assets/screenshots/setup.png)

### 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.

### Option 1 : Docker Compose (recommandé)

`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`).

> [!WARNING]
>
> 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](#upgrading-a-docker-compose-installation)). 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](#replacing-the-secret-key) donne cette valeur et la modification à faire.

```bash
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](#environment-variables) 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.

> [!WARNING]
>
> 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](https://github.com/Notifuse/notifuse/blob/main/CHANGELOG.md) entre votre version et la nouvelle, faites une [sauvegarde](https://www.notifuse.com/fr/docs/self-hosting/backups.md), 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](https://www.notifuse.com/fr/docs/self-hosting/upgrading-postgresql.md) 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 :

```bash
# 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](#environment-variables).

### 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](https://www.notifuse.com/fr/docs/features/templates.md#view-in-browser) 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.

> [!WARNING]
>
> **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 :
>
> ```bash
> # ✅ 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

| Variable      | Description                                                                        |
| ------------- | ---------------------------------------------------------------------------------- |
| `DB_HOST`     | Hôte PostgreSQL (par exemple `localhost` ou `db.yourcompany.com`)                  |
| `DB_PORT`     | Port PostgreSQL (par exemple `5432`)                                               |
| `DB_USER`     | Nom d'utilisateur de la base (par exemple `postgres`)                              |
| `DB_PASSWORD` | Mot de passe de la base (par exemple `postgres`)                                   |
| `SECRET_KEY`  | Clé secrète de chiffrement et de signature (à générer avec la commande ci-dessous) |

**Générer SECRET_KEY :**

```bash
openssl rand -base64 32
```

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

> [!WARNING]
>
> 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](#replacing-the-secret-key).

### 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.

> [!WARNING]
>
> 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 :
>
> ```bash
> # 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.

| Variable             | Description                                                                                                                                                                                                                                                                                                |
| -------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `ROOT_EMAIL`         | Email 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_ENDPOINT`       | URL publique de l'endpoint de l'API (par exemple `https://emails.yourcompany.com`). Pour passer plus tard à un autre domaine, voir [Changer de domaine](https://www.notifuse.com/fr/docs/self-hosting/changing-domain.md).                                                                                 |
| `SMTP_HOST`          | Hôte du serveur SMTP (par exemple `smtp.gmail.com`)                                                                                                                                                                                                                                                        |
| `SMTP_PORT`          | Port du serveur SMTP (par exemple `587` ou `465`)                                                                                                                                                                                                                                                          |
| `SMTP_USERNAME`      | Nom d'utilisateur SMTP (par exemple `noreply@yourcompany.com`)                                                                                                                                                                                                                                             |
| `SMTP_PASSWORD`      | Mot de passe SMTP (par exemple `your_smtp_password`)                                                                                                                                                                                                                                                       |
| `SMTP_FROM_EMAIL`    | Adresse d'expédition (par exemple `noreply@yourcompany.com`)                                                                                                                                                                                                                                               |
| `SMTP_FROM_NAME`     | Nom d'expéditeur (par exemple `Your Company Name`)                                                                                                                                                                                                                                                         |
| `SMTP_EHLO_HOSTNAME` | Nom 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

| Variable                                                                                                       | Description                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                               | Par défaut                              |
| -------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------- |
|                                                                                                                |
| **Configuration du serveur**                                                                                   |
| `SERVER_PORT`                                                                                                  | Port d'écoute du serveur (par exemple `8080`)                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                             | `8080`                                  |
| `SERVER_HOST`                                                                                                  | Adresse d'hôte à laquelle se lier (par exemple `0.0.0.0`)                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                 | `0.0.0.0`                               |
| `CORS_ALLOW_ORIGIN`                                                                                            | Origines 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.                                                                                                                                                                                                                    | `*`                                     |
| `ENVIRONMENT`                                                                                                  | Mode d'environnement (par exemple `production`)                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                           | `production`                            |
| `LOG_LEVEL`                                                                                                    | Niveau de log (par exemple `debug` ou `warn`)                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                             | `info`                                  |
|                                                                                                                |
| **Configuration de la base de données**                                                                        |
| `DB_PREFIX`                                                                                                    | Préfixe du nom des bases système et d'espace de travail (par exemple `notifuse` pour `notifuse_system` et `notifuse_ws_*`)                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                | `notifuse`                              |
| `DB_NAME`                                                                                                      | Nom de la base (par exemple `notifuse_system`)                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                            | `${DB_PREFIX}_system`                   |
| `DB_SSLMODE`                                                                                                   | Mode SSL de la base (par exemple `require` ou `disable`)                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  | `require`                               |
| `DB_EXPECT_EXISTING`                                                                                           | `true` 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 installation                                                                                                                                                                                                                                                                                                                               | `false`                                 |
| `DB_MAX_CONNECTIONS`                                                                                           | Nombre maximal de connexions, toutes bases confondues (par exemple `100`)                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                 | `100`                                   |
| `DB_MAX_CONNECTIONS_PER_DB`                                                                                    | Nombre maximal de connexions par base d'espace de travail (par exemple `3`)                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                               | `3`                                     |
| `DB_CONNECTION_MAX_LIFETIME`                                                                                   | Durée de vie maximale d'une connexion (par exemple `10m`)                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                 | `10m`                                   |
| `DB_CONNECTION_MAX_IDLE_TIME`                                                                                  | Durée d'inactivité maximale avant la fermeture d'une connexion (par exemple `5m`)                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                         | `5m`                                    |
|                                                                                                                |
| **Configuration du planificateur de tâches**                                                                   |
| `TASK_SCHEDULER_ENABLED`                                                                                       | Active le planificateur de tâches interne (par exemple `true` ou `false`)                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                 | `true`                                  |
| `TASK_SCHEDULER_INTERVAL`                                                                                      | Intervalle d'exécution des tâches, en secondes (par exemple `30`)                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                         | `30`                                    |
| `TASK_SCHEDULER_MAX_TASKS`                                                                                     | Nombre maximal de tâches simultanées (par exemple `10`)                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                   | `10`                                    |
|                                                                                                                |
| **Configuration des newsletters**                                                                              |
| `BROADCAST_DATA_FEED_ALLOW_PRIVATE_HOSTS`                                                                      | Autorise les [data feeds](https://www.notifuse.com/fr/docs/features/broadcast-campaigns.md) 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_CONCURRENCY`                                                                                      | Nombre 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](https://www.notifuse.com/fr/docs/features/broadcast-campaigns.md#sending-speed).                                                                                                                                                                                                                                                                                                            | `10`                                    |
| `EMAIL_QUEUE_SMTP_CONCURRENCY`                                                                                 | La 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_HOSTS`                                                                         | Autorise les webhooks sortants ([abonnements webhook](https://www.notifuse.com/fr/docs/features/webhooks.md) et [nœuds webhook des automations](https://www.notifuse.com/fr/docs/features/automations.md#webhook-node)) à 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_KEY`                                                                                         | Une [clé de licence](https://www.notifuse.com/fr/docs/self-hosting/licence.md) auto-hébergée. L'emporte sur une clé collée dans la console. Inutile pour faire tourner Notifuse.                                                                                                                                                                                                                                                                                                                                                                                                                                                          | -                                       |
|                                                                                                                |
| **Confidentialité**                                                                                            |
| `TELEMETRY`                                                                                                    | Envoie des statistiques d'utilisation anonymes (par exemple `true` ou `false`)                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                            | `true`                                  |
| `CHECK_FOR_UPDATES`                                                                                            | Vérifie la disponibilité de nouvelles versions (par exemple `true` ou `false`)                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                            | `true`                                  |
|                                                                                                                |
| **Configuration de la passerelle SMTP**                                                                        |
| `SMTP_BRIDGE_ENABLED`                                                                                          | Active le serveur de passerelle SMTP pour les emails transactionnels (par exemple `true` ou `false`)                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      | `false`                                 |
| `SMTP_BRIDGE_PORT`                                                                                             | Port de la passerelle SMTP (par exemple `587` pour STARTTLS, `465` pour le TLS implicite)                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                 | `587`                                   |
| `SMTP_BRIDGE_DOMAIN`                                                                                           | Nom de domaine public de la passerelle SMTP (par exemple `smtp.yourdomain.com`)                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                           | `localhost`                             |
| `SMTP_BRIDGE_TLS`                                                                                              | Mode TLS : `starttls`, `implicit` ou `off` (voir plus bas). Déterminé automatiquement s'il n'est pas défini.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                              | auto                                    |
| `SMTP_BRIDGE_TLS_CERT_BASE64`                                                                                  | Certificat TLS encodé en base64 (requis pour `starttls` et `implicit`)                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                    | -                                       |
| `SMTP_BRIDGE_TLS_KEY_BASE64`                                                                                   | Clé privée TLS encodée en base64 (requise pour `starttls` et `implicit`)                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  | -                                       |
|                                                                                                                |
| **Authentification unique (OIDC)** (voir le [guide SSO](https://www.notifuse.com/fr/docs/self-hosting/sso.md)) |                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                           |                                         |
| `OIDC_ENABLED`                                                                                                 | Active l'authentification unique via OpenID Connect (par exemple `true` ou `false`)                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                       | `false`                                 |
| `OIDC_ISSUER_URL`                                                                                              | URL de l'émetteur de l'IdP, obligatoirement en https (par exemple `https://accounts.google.com`)                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                          | -                                       |
| `OIDC_CLIENT_ID`                                                                                               | Client ID OAuth2 fourni par votre fournisseur d'identité                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  | -                                       |
| `OIDC_CLIENT_SECRET`                                                                                           | Client secret OAuth2 (chiffré au repos, jamais envoyé au navigateur)                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      | -                                       |
| `OIDC_REDIRECT_URI`                                                                                            | URL de callback enregistrée chez l'IdP. Dérivée de `API_ENDPOINT` si elle est vide.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                       | `<API_ENDPOINT>/api/user.oidc.callback` |
| `OIDC_SCOPES`                                                                                                  | Scopes séparés par des espaces (`openid` toujours inclus)                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                 | `openid email profile`                  |
| `OIDC_BUTTON_LABEL`                                                                                            | Libellé du bouton de connexion                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                            | `Sign in with SSO`                      |
| `OIDC_AUTO_CREATE_USERS`                                                                                       | Crée automatiquement les comptes à la première connexion SSO (demande `OIDC_ALLOWED_DOMAINS`)                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                             | `false`                                 |
| `OIDC_ALLOWED_DOMAINS`                                                                                         | Liste 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_ENABLED`                                                                                              | Active le tracing (par exemple `true`)                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                    | `false`                                 |
| `TRACING_SERVICE_NAME`                                                                                         | Nom du service pour le tracing (par exemple `notifuse-production`)                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        | `notifuse-api`                          |
| `TRACING_SAMPLING_PROBABILITY`                                                                                 | Probabilité d'échantillonnage (par exemple `0.05`)                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        | `0.1`                                   |
| `TRACING_TRACE_EXPORTER`                                                                                       | Exportateur de traces : jaeger/zipkin/stackdriver/datadog/xray/none (par exemple `jaeger` ou `datadog`)                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                   | `none`                                  |
| `TRACING_JAEGER_ENDPOINT`                                                                                      | Endpoint Jaeger (par exemple `http://jaeger:14268/api/traces`)                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                            | `http://localhost:14268/api/traces`     |
| `TRACING_ZIPKIN_ENDPOINT`                                                                                      | Endpoint Zipkin (par exemple `http://zipkin:9411/api/v2/spans`)                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                           | `http://localhost:9411/api/v2/spans`    |
| `TRACING_STACKDRIVER_PROJECT_ID`                                                                               | ID de projet Stackdriver (par exemple `my-gcp-project-id`)                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                | -                                       |
| `TRACING_AZURE_INSTRUMENTATION_KEY`                                                                            | Clé d'instrumentation Azure Monitor (par exemple `12345678-1234-1234-1234-123456789012`)                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  | -                                       |
| `TRACING_DATADOG_AGENT_ADDRESS`                                                                                | Adresse de l'agent Datadog (par exemple `datadog-agent:8126`)                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                             | `localhost:8126`                        |
| `TRACING_DATADOG_API_KEY`                                                                                      | Clé API Datadog (par exemple `1234567890abcdef1234567890abcdef`)                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                          | -                                       |
| `TRACING_XRAY_REGION`                                                                                          | Région AWS X-Ray (par exemple `us-east-1`)                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                | `us-west-2`                             |
| `TRACING_AGENT_ENDPOINT`                                                                                       | Endpoint d'agent générique (par exemple `monitoring-agent:8126`)                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                          | `localhost:8126`                        |
| `TRACING_METRICS_EXPORTER`                                                                                     | Exportateur de métriques : stackdriver/prometheus/datadog/none (par exemple `prometheus`)                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                 | `none`                                  |
| `TRACING_PROMETHEUS_PORT`                                                                                      | Port 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](https://www.notifuse.com/fr/docs/features/transactional-api.md#smtp-bridge) pour des exemples d'envoi une fois la configuration faite.

### Modes TLS

La passerelle prend en charge trois modes TLS via `SMTP_BRIDGE_TLS` :

| Mode       | Description                                                                                                                                               | Port 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`         |
| `implicit` | TLS dès le premier octet (SMTPS). Requis pour les clients qui ne parlent que le TLS implicite.                                                            | `465`         |
| `off`      | Pas 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.

> [!WARNING]
>
> 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

```bash
# 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.

```bash
# 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 :

```bash
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 :

```bash
# 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` :

```bash
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 :

```bash
# 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.

```bash
#!/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.

> [!WARNING]
>
> 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](https://cloud.notifuse.com).

- [PikaPods](https://www.pikapods.com/pods?run=notifuse)
- [RepoCloud](https://repocloud.io/details/Notifuse/?ref=67eysha)
- [Sealos](https://sealos.io/products/app-store/notifuse)
- [Northflank](https://northflank.com/stacks/deploy-notifuse)
