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

# Installazione self-hosted

> Come installare Notifuse sul tuo server

> [!TIP]
>
> **Cerchi una soluzione gestita?** [Notifuse Cloud](https://cloud.notifuse.com) si occupa di hosting, sicurezza, backup, aggiornamenti e manutenzione, a partire da **16 $/mese**.

## Per iniziare

Notifuse include una **procedura guidata di configurazione** interattiva. Molte variabili d'ambiente sono facoltative e puoi impostarle dall'interfaccia web al primo avvio.

![La procedura guidata di configurazione compilata: amministratore, invio delle email di sistema (SMTP), aggiornamenti e telemetria, single sign-on e bridge SMTP, con accanto ciò che resta da compilare](https://www.notifuse.com/docs/assets/screenshots/setup.png)

### Avvio rapido con la procedura guidata

1. Installa Notifuse con una delle opzioni qui sotto
2. Apri la tua istanza in un browser
3. Completa la procedura guidata di configurazione:
   - Inserisci l'email dell'amministratore root (una o più)
   - Controlla l'endpoint dell'API, già compilato con l'indirizzo della pagina
   - Configura il server SMTP che invia i codici di accesso e gli inviti, poi prova la connessione
   - Mantieni o disattiva il controllo degli aggiornamenti e la telemetria anonima (entrambi attivi per impostazione predefinita)
   - Se vuoi, configura il single sign-on (OpenID Connect) e il bridge SMTP
4. Inizia a usare Notifuse.

Un'impostazione già fornita da una variabile d'ambiente appare bloccata nella procedura guidata, con il nome della variabile, e la procedura non la chiede.

### Opzione 1: Docker Compose (consigliata)

`compose.yaml` avvia Notifuse con il suo PostgreSQL 18. Il file basta da solo: sul server non serve un clone del repository, ma solo Docker Engine 25.0 e Compose v2.24 o versioni successive (`docker compose version`).

> [!WARNING]
>
> Questi passaggi creano una nuova installazione. Per aggiornarne una in funzione, conserva il suo `.env` e la `SECRET_KEY` che contiene: una nuova chiave da sola rende illeggibili i dati salvati (vedi [Aggiornamento](#upgrading-a-docker-compose-installation)). Un'installazione avviata da `compose.yaml` prima della versione 42.0 senza impostare `SECRET_KEY` usa un valore predefinito che Notifuse ora rifiuta: [Sostituire la chiave segreta](#replacing-the-secret-key) riporta quel valore e la modifica da fare.

```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 parte così sulla porta `8081`, con PostgreSQL raggiungibile solo dal server stesso (`127.0.0.1:5433`). Al primo avvio la procedura guidata ti accompagna nella configurazione. Puoi anche impostare le [variabili d'ambiente](#environment-variables) nel file `.env`: ogni variabile che contiene arriva a Notifuse.

Notifuse serve HTTP in chiaro. Metti davanti un reverse proxy con TLS prima di puntarci un dominio, e imposta `HTTP_BIND=127.0.0.1` in `.env` se il proxy gira sullo stesso server.

> [!WARNING]
>
> Compose dà al volume del database il nome della cartella che contiene `compose.yaml` (qui `notifuse_postgres-data`). Non rinominare quella cartella: in una cartella rinominata o spostata, `docker compose up -d` avvia una nuova installazione su un database vuoto. `docker compose down -v` elimina il database.

#### Aggiornare un'installazione Docker Compose

Leggi le voci del [changelog](https://github.com/Notifuse/notifuse/blob/main/CHANGELOG.md) tra la tua versione e quella nuova, [fai un backup](https://www.notifuse.com/it/docs/self-hosting/backups.md), poi scarica il `compose.yaml` della nuova release sopra il tuo (oppure imposta `NOTIFUSE_VERSION=v44.0` in `.env` per scegliere la release) ed esegui `docker compose up -d`.

La versione 44.0 porta `compose.yaml` a PostgreSQL 18: il primo `docker compose up -d` copia i dati di PostgreSQL 17 in un secondo volume e poi li aggiorna. [Aggiornare PostgreSQL](https://www.notifuse.com/it/docs/self-hosting/upgrading-postgresql.md) spiega cosa succede, come verificarlo e come tornare indietro.

#### Da un clone del repository

Lo stesso file compila Notifuse dai sorgenti in un clone: `docker compose up -d --build`, oppure `docker compose watch` per ricompilare a ogni modifica. Senza `--build` esegue l'immagine pubblicata per la release indicata nel file; una release non ancora pubblicata, sul branch `dev`, viene compilata dal checkout. Fino alla versione 43, `compose.yaml` compilava sempre dal checkout.

### Opzione 2: Docker standalone (produzione)

Per i deployment in produzione, usa l'immagine Docker standalone con il tuo database 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
```

Al primo avvio la procedura guidata ti accompagna nella configurazione. Puoi anche impostare le [variabili d'ambiente](#environment-variables).

### Database PostgreSQL (solo opzione 2)

Con l'opzione Docker standalone puoi usare qualsiasi database PostgreSQL **con credenziali root**. Notifuse crea il proprio database di sistema.

**Versione**: PostgreSQL 17 o successiva (Notifuse non parte su un server più vecchio); `compose.yaml` include PostgreSQL 18

Notifuse crea un database per ogni workspace, per evitare i problemi del multi-tenant. Per questo gli servono le credenziali root.

**Nota**: Docker Compose include già PostgreSQL, quindi lì questo punto non si applica.

### Un server SMTP

Notifuse ha bisogno di un server SMTP per inviare le email di sistema, come i codici di accesso e gli inviti.

Con SES puoi creare le credenziali SMTP nella sezione delle impostazioni SMTP della dashboard di SES.

### Un endpoint API pubblico

Notifuse ha bisogno di un endpoint API pubblico raggiungibile dal web, per esempio `https://emails.yourcompany.com`.

Dietro un reverse proxy, inoltra a Notifuse l'header `Host` originale, oppure impostalo in `X-Forwarded-Host`. Le [versioni web](https://www.notifuse.com/it/docs/features/templates.md#view-in-browser) delle email si aprono solo sul dominio con cui è stato inviato il loro link e su `API_ENDPOINT`. Un proxy che sostituisce `Host` con il proprio indirizzo upstream senza impostare `X-Forwarded-Host` rende indisponibili tutte le versioni web; uno che lo sostituisce con l'host di `API_ENDPOINT` permette a ogni dominio personalizzato di mostrare le versioni web di tutti i workspace.

## Variabili d'ambiente

Con la procedura guidata di configurazione molte variabili d'ambiente sono facoltative e puoi impostarle dall'interfaccia web. Una variabile d'ambiente impostata ha sempre la precedenza sull'impostazione salvata nel database.

> [!WARNING]
>
> **Caratteri speciali nei file .env**
>
> In un file `.env`, un valore che contiene il carattere `#` (frequente nelle password) **deve** stare tra virgolette:
>
> ```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"
> ```
>
> Vale solo per i file `.env`, non per le variabili impostate direttamente nella shell, in Docker Compose o in una piattaforma di orchestrazione dei container.

### Variabili obbligatorie

| Variabile     | Descrizione                                                              |
| ------------- | ------------------------------------------------------------------------ |
| `DB_HOST`     | Host di PostgreSQL (es. `localhost` o `db.yourcompany.com`)              |
| `DB_PORT`     | Porta di PostgreSQL (es. `5432`)                                         |
| `DB_USER`     | Nome utente del database (es. `postgres`)                                |
| `DB_PASSWORD` | Password del database (es. `postgres`)                                   |
| `SECRET_KEY`  | Chiave segreta per cifratura e firma (generala con il comando qui sotto) |

**Genera la SECRET_KEY:**

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

Notifuse non parte con una `SECRET_KEY` che dà meno di 32 byte.

> [!WARNING]
>
> Non sostituire mai la tua `SECRET_KEY` con un nuovo valore da solo. La chiave cifra tutti i segreti
> delle integrazioni dei workspace (API key dei provider email, password SMTP, ecc.), che una nuova
> chiave da sola non riesce a leggere. Per cambiarla, segui [Sostituire la chiave segreta](#replacing-the-secret-key).

### Sostituire la chiave segreta

`SECRET_KEY` può elencare più chiavi separate da virgole (una virgola che fa parte di una chiave si scrive
due volte). La prima chiave cifra e firma; le altre servono solo a Notifuse per leggere i dati salvati con
esse. Quando Notifuse parte con un elenco, ricifra quei dati con la prima chiave, in un'unica transazione,
prima di servire qualsiasi richiesta. Per sostituire la chiave:

1. Genera una nuova chiave con `openssl rand -base64 32`.
2. Mettila per prima, seguita dalla chiave attuale: `SECRET_KEY=<new key>,<current key>`. Se la chiave
   attuale contiene una virgola, scrivila due volte; se inizia o finisce con una virgola, metti uno spazio
   tra quella e la virgola che separa le chiavi (`SECRET_KEY=<new key>, ,,<rest of the key>`). Una versione
   precedente alla 42.0 legge l'intero elenco come un'unica chiave: quando passi alla 42.0, imposta
   l'elenco nello stesso passaggio.
3. Ferma tutte le istanze di Notifuse, poi riavviale tutte con quel valore. Un'istanza ancora in funzione
   con la sola chiave attuale non legge i dati che le altre hanno ricifrato, e un'istanza con l'elenco non
   legge ciò che quell'istanza scrive fino al successivo avvio con l'elenco.
4. Quando tutte le istanze girano con quel valore, imposta `SECRET_KEY` sulla sola nuova chiave, senza
   virgolette né spazi intorno: una chiave singola viene usata esattamente come è scritta. Se non apre
   nessuno dei workspace salvati (o, finché non ce n'è nessuno, nessuna delle impostazioni di sistema
   cifrate), Notifuse non parte.

Se la chiave di un workspace, o una credenziale che usa, non si apre con nessuna delle chiavi elencate,
Notifuse non parte, non modifica nulla e indica quel workspace. Un'impostazione di sistema cifrata che
nessuna chiave apre (una credenziale SMTP o il client secret OIDC salvati nella procedura guidata, il
certificato o la chiave TLS del bridge SMTP) resta com'è e viene indicata in un avviso nei log di avvio, e
Notifuse funziona senza di essa: per conservarla, elenca la chiave con cui è cifrata. Notifuse non parte, e
indica l'impostazione, quando il single sign-on o il bridge SMTP sono attivi e ne hanno bisogno, oppure
quando non c'è ancora nessun workspace e nessuna di quelle impostazioni si apre.

Sostituire la chiave disconnette tutti. Le API key vanno eliminate e ricreate, gli inviti in sospeso vanno
inviati di nuovo, e gli script che chiamano `user.rootSignin` firmano con la nuova chiave. Un client API
che salva un'integrazione con le credenziali cifrate lette prima della modifica viene rifiutato finché non
rilegge il workspace. I backup del database fatti prima della modifica richiedono ancora la vecchia chiave.
I dati conservati nel database di ogni workspace, come la cronologia dei messaggi, sono cifrati con la
chiave propria di quel workspace e non cambiano.

> [!WARNING]
>
> Prima della versione 42.0, `compose.yaml` forniva una `SECRET_KEY` predefinita e `env.example` un
> segnaposto. Notifuse non parte quando la prima chiave di `SECRET_KEY` è uno di questi valori o dà meno
> di 32 byte, e legge una virgola singola come separatore tra le chiavi: se la tua chiave contiene una
> virgola, scrivi ognuna delle sue virgole due volte quando aggiorni. Se la tua installazione usa uno di
> questi valori, sostituiscilo come sopra, tenendolo dopo la nuova chiave, nello stesso passaggio
> dell'aggiornamento alla 42.0. Se sei partito da `compose.yaml` senza impostare `SECRET_KEY`, la tua
> chiave attuale è il vecchio valore predefinito:
>
> ```bash
> # Put the output of openssl rand -base64 32 before the comma
> SECRET_KEY=<new key>,d04zCk3Fa45oOjDWHpAvc1AZxnLdGffOnNWK+Jt2yXf37+FTfuMMHb8flcfPMqLluRR3rvhbr555r6j1DEigrA==
> ```

### Variabili dell'applicazione (facoltative con la procedura guidata)

Impostale nella procedura guidata al primo avvio, oppure come variabili d'ambiente, che hanno sempre la precedenza sulla procedura guidata.

| Variabile            | Descrizione                                                                                                                                                                                                                                                           |
| -------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `ROOT_EMAIL`         | Email dell'amministratore root (es. `admin@yourcompany.com`). Accetta più email separate da virgole o punti e virgola per dare i privilegi root a più amministratori (es. `alice@yourcompany.com,bob@yourcompany.com`); il confronto distingue maiuscole e minuscole. |
| `API_ENDPOINT`       | URL pubblico dell'endpoint API (es. `https://emails.yourcompany.com`). Per passare in seguito a un altro dominio, vedi [Cambiare dominio](https://www.notifuse.com/it/docs/self-hosting/changing-domain.md).                                                          |
| `SMTP_HOST`          | Host del server SMTP (es. `smtp.gmail.com`)                                                                                                                                                                                                                           |
| `SMTP_PORT`          | Porta del server SMTP (es. `587` o `465`)                                                                                                                                                                                                                             |
| `SMTP_USERNAME`      | Nome utente SMTP (es. `noreply@yourcompany.com`)                                                                                                                                                                                                                      |
| `SMTP_PASSWORD`      | Password SMTP (es. `your_smtp_password`)                                                                                                                                                                                                                              |
| `SMTP_FROM_EMAIL`    | Indirizzo del mittente (es. `noreply@yourcompany.com`)                                                                                                                                                                                                                |
| `SMTP_FROM_NAME`     | Nome del mittente (es. `Your Company Name`)                                                                                                                                                                                                                           |
| `SMTP_EHLO_HOSTNAME` | Hostname EHLO personalizzato per le connessioni SMTP (es. `mail.yourdomain.com`). Se vuoto, usa l'host SMTP. Utile quando i server SMTP rifiutano `EHLO localhost`.                                                                                                   |

> [!NOTE]
>
> **Più utenti root**: `ROOT_EMAIL` può contenere più email (separate da
> virgole o punti e virgola), così un'istanza condivisa può avere più
> amministratori con privilegi root: creare workspace, accedere alle
> impostazioni di sistema e autenticarsi in modo programmatico. All'avvio
> Notifuse crea un account utente per ogni email elencata, quindi ogni root può
> accedere subito. Il confronto distingue maiuscole e minuscole, e un'unica
> email funziona esattamente come prima. La procedura guidata imposta il primo
> root (quello principale); puoi aggiungerne altri lì sotto forma di elenco o
> con la variabile d'ambiente `ROOT_EMAIL`.

### Variabili facoltative

| Variabile                                                                                             | Descrizione                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                    | Predefinito                             |
| ----------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------- |
|                                                                                                       |
| **Configurazione del server**                                                                         |
| `SERVER_PORT`                                                                                         | Porta su cui il server è in ascolto (es. `8080`)                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                               | `8080`                                  |
| `SERVER_HOST`                                                                                         | Indirizzo host a cui collegarsi (es. `0.0.0.0`)                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                | `0.0.0.0`                               |
| `CORS_ALLOW_ORIGIN`                                                                                   | Origini autorizzate a chiamare l'API da un browser: `*`, una sola origine o un elenco separato da virgole (es. `https://yourapp.com,https://admin.yourapp.com`; gli elenchi richiedono la 41.1 o successiva). Un valore ristretto deve includere ogni dominio personalizzato dei workspace, perché la loro console e il loro centro notifiche chiamano l'API dalla propria origine.                                                                                                                                                                                                            | `*`                                     |
| `ENVIRONMENT`                                                                                         | Modalità dell'ambiente (es. `production`)                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      | `production`                            |
| `LOG_LEVEL`                                                                                           | Livello di log (es. `debug` o `warn`)                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                          | `info`                                  |
|                                                                                                       |
| **Configurazione del database**                                                                       |
| `DB_PREFIX`                                                                                           | Prefisso del nome per i database di sistema e dei workspace (es. `notifuse` per `notifuse_system` e `notifuse_ws_*`)                                                                                                                                                                                                                                                                                                                                                                                                                                                                           | `notifuse`                              |
| `DB_NAME`                                                                                             | Nome del database (es. `notifuse_system`)                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      | `${DB_PREFIX}_system`                   |
| `DB_SSLMODE`                                                                                          | Modalità SSL del database (es. `require` o `disable`)                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                          | `require`                               |
| `DB_EXPECT_EXISTING`                                                                                  | `true` impedisce di creare o inizializzare il database di sistema e di creare un database di workspace mancante. Impostala su un server che deve già contenere i dati (un aggiornamento, un ripristino), così un PostgreSQL vuoto ferma Notifuse invece di avviare una nuova installazione                                                                                                                                                                                                                                                                                                     | `false`                                 |
| `DB_MAX_CONNECTIONS`                                                                                  | Numero massimo di connessioni su tutti i database (es. `100`)                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  | `100`                                   |
| `DB_MAX_CONNECTIONS_PER_DB`                                                                           | Numero massimo di connessioni per database di workspace (es. `3`)                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                              | `3`                                     |
| `DB_CONNECTION_MAX_LIFETIME`                                                                          | Durata massima di una connessione (es. `10m`)                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  | `10m`                                   |
| `DB_CONNECTION_MAX_IDLE_TIME`                                                                         | Tempo massimo di inattività prima di chiudere la connessione (es. `5m`)                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        | `5m`                                    |
|                                                                                                       |
| **Configurazione del task scheduler**                                                                 |
| `TASK_SCHEDULER_ENABLED`                                                                              | Attiva lo scheduler interno dei task (es. `true` o `false`)                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                    | `true`                                  |
| `TASK_SCHEDULER_INTERVAL`                                                                             | Intervallo di esecuzione dei task in secondi (es. `30`)                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        | `30`                                    |
| `TASK_SCHEDULER_MAX_TASKS`                                                                            | Numero massimo di task simultanei (es. `10`)                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                   | `10`                                    |
|                                                                                                       |
| **Configurazione dei broadcast**                                                                      |
| `BROADCAST_DATA_FEED_ALLOW_PRIVATE_HOSTS`                                                             | Permette ai [data feed](https://www.notifuse.com/it/docs/features/broadcast-campaigns.md) dei broadcast di leggere da indirizzi privati, di loopback e link-local. Questo **disattiva la protezione SSRF** per le richieste dei data feed: attivala solo in deployment fidati che leggono di proposito i feed dalla tua rete interna (es. `true`).                                                                                                                                                                                                                                             | `false`                                 |
| `EMAIL_QUEUE_CONCURRENCY`                                                                             | Email che ogni integrazione email diversa da SMTP invia contemporaneamente per broadcast e automazioni, per istanza di Notifuse, tra 1 e 50 (es. `20`; 42.0 o successiva). Vedi [Velocità di invio](https://www.notifuse.com/it/docs/features/broadcast-campaigns.md#sending-speed).                                                                                                                                                                                                                                                                                                           | `10`                                    |
| `EMAIL_QUEUE_SMTP_CONCURRENCY`                                                                        | Lo stesso per le integrazioni SMTP, tra 1 e 50 (42.0 o successiva). Aumentala solo se il tuo server SMTP accetta più connessioni alla volta (es. `4`).                                                                                                                                                                                                                                                                                                                                                                                                                                         | `1`                                     |
|                                                                                                       |
| **Configurazione dei webhook**                                                                        |
| `WEBHOOK_DELIVERY_ALLOW_PRIVATE_HOSTS`                                                                | Permette ai webhook in uscita ([subscription webhook](https://www.notifuse.com/it/docs/features/webhooks.md) e [nodi webhook delle automazioni](https://www.notifuse.com/it/docs/features/automations.md#webhook-node)) di raggiungere indirizzi privati, di loopback e link-local. Questo **disattiva la protezione SSRF** per loro: attivala solo in deployment fidati che consegnano di proposito webhook alla tua rete interna, come n8n sulla stessa rete Docker (es. `true`). Finché è disattivata, i webhook in uscita si collegano direttamente e ignorano `HTTP_PROXY`/`HTTPS_PROXY`. | `false`                                 |
|                                                                                                       |
| **Licenza**                                                                                           |
| `NOTIFUSE_LICENSE_KEY`                                                                                | Una [chiave di licenza](https://www.notifuse.com/it/docs/self-hosting/licence.md) self-hosted. Prevale su una chiave incollata nella console. Non serve per far funzionare Notifuse.                                                                                                                                                                                                                                                                                                                                                                                                           | -                                       |
|                                                                                                       |
| **Impostazioni sulla privacy**                                                                        |
| `TELEMETRY`                                                                                           | Invia statistiche d'uso anonime (es. `true` o `false`)                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                         | `true`                                  |
| `CHECK_FOR_UPDATES`                                                                                   | Controlla la disponibilità di nuove versioni (es. `true` o `false`)                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                            | `true`                                  |
|                                                                                                       |
| **Configurazione del bridge SMTP**                                                                    |
| `SMTP_BRIDGE_ENABLED`                                                                                 | Attiva il server bridge SMTP per le email transazionali (es. `true` o `false`)                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                 | `false`                                 |
| `SMTP_BRIDGE_PORT`                                                                                    | Porta del bridge SMTP (es. `587` per STARTTLS, `465` per TLS implicito)                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        | `587`                                   |
| `SMTP_BRIDGE_DOMAIN`                                                                                  | Nome di dominio pubblico del bridge SMTP (es. `smtp.yourdomain.com`)                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                           | `localhost`                             |
| `SMTP_BRIDGE_TLS`                                                                                     | Modalità TLS: `starttls`, `implicit` o `off` (vedi sotto). Se non è impostata, viene scelta automaticamente.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                   | auto                                    |
| `SMTP_BRIDGE_TLS_CERT_BASE64`                                                                         | Certificato TLS codificato in Base64 (obbligatorio per `starttls` e `implicit`)                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                | -                                       |
| `SMTP_BRIDGE_TLS_KEY_BASE64`                                                                          | Chiave privata TLS codificata in Base64 (obbligatoria per `starttls` e `implicit`)                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                             | -                                       |
|                                                                                                       |
| **Single sign-on (OIDC)** (vedi la [guida SSO](https://www.notifuse.com/it/docs/self-hosting/sso.md)) |                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                |                                         |
| `OIDC_ENABLED`                                                                                        | Attiva il single sign-on tramite OpenID Connect (es. `true` o `false`)                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                         | `false`                                 |
| `OIDC_ISSUER_URL`                                                                                     | URL dell'issuer dell'IdP, deve essere https (es. `https://accounts.google.com`)                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                | -                                       |
| `OIDC_CLIENT_ID`                                                                                      | Client ID OAuth2 del tuo identity provider                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                     | -                                       |
| `OIDC_CLIENT_SECRET`                                                                                  | Client secret OAuth2 (cifrato a riposo, mai inviato al browser)                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                | -                                       |
| `OIDC_REDIRECT_URI`                                                                                   | URL di callback registrato presso l'IdP. Se vuoto, è derivato da `API_ENDPOINT`.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                               | `<API_ENDPOINT>/api/user.oidc.callback` |
| `OIDC_SCOPES`                                                                                         | Scope separati da spazi (`openid` è sempre incluso)                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                            | `openid email profile`                  |
| `OIDC_BUTTON_LABEL`                                                                                   | Testo del pulsante di accesso                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  | `Sign in with SSO`                      |
| `OIDC_AUTO_CREATE_USERS`                                                                              | Crea automaticamente gli account al primo accesso SSO (richiede `OIDC_ALLOWED_DOMAINS`)                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        | `false`                                 |
| `OIDC_ALLOWED_DOMAINS`                                                                                | Elenco dei domini email autorizzati, separati da virgole o punti e virgola, che limita la creazione automatica                                                                                                                                                                                                                                                                                                                                                                                                                                                                                 | -                                       |
|                                                                                                       |
| **Configurazione del tracing**                                                                        |
| `TRACING_ENABLED`                                                                                     | Attiva il tracing (es. `true`)                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                 | `false`                                 |
| `TRACING_SERVICE_NAME`                                                                                | Nome del servizio per il tracing (es. `notifuse-production`)                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                   | `notifuse-api`                          |
| `TRACING_SAMPLING_PROBABILITY`                                                                        | Probabilità di campionamento (es. `0.05`)                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      | `0.1`                                   |
| `TRACING_TRACE_EXPORTER`                                                                              | Exporter delle tracce: jaeger/zipkin/stackdriver/datadog/xray/none (es. `jaeger` o `datadog`)                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  | `none`                                  |
| `TRACING_JAEGER_ENDPOINT`                                                                             | Endpoint di Jaeger (es. `http://jaeger:14268/api/traces`)                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      | `http://localhost:14268/api/traces`     |
| `TRACING_ZIPKIN_ENDPOINT`                                                                             | Endpoint di Zipkin (es. `http://zipkin:9411/api/v2/spans`)                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                     | `http://localhost:9411/api/v2/spans`    |
| `TRACING_STACKDRIVER_PROJECT_ID`                                                                      | ID del progetto Stackdriver (es. `my-gcp-project-id`)                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                          | -                                       |
| `TRACING_AZURE_INSTRUMENTATION_KEY`                                                                   | Chiave di strumentazione di Azure Monitor (es. `12345678-1234-1234-1234-123456789012`)                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                         | -                                       |
| `TRACING_DATADOG_AGENT_ADDRESS`                                                                       | Indirizzo dell'agent Datadog (es. `datadog-agent:8126`)                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        | `localhost:8126`                        |
| `TRACING_DATADOG_API_KEY`                                                                             | API key di Datadog (es. `1234567890abcdef1234567890abcdef`)                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                    | -                                       |
| `TRACING_XRAY_REGION`                                                                                 | Regione di AWS X-Ray (es. `us-east-1`)                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                         | `us-west-2`                             |
| `TRACING_AGENT_ENDPOINT`                                                                              | Endpoint generico dell'agent (es. `monitoring-agent:8126`)                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                     | `localhost:8126`                        |
| `TRACING_METRICS_EXPORTER`                                                                            | Exporter delle metriche: stackdriver/prometheus/datadog/none (es. `prometheus`)                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                | `none`                                  |
| `TRACING_PROMETHEUS_PORT`                                                                             | Porta delle metriche Prometheus (es. `9464`)                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                   | `9464`                                  |

## Configurazione del bridge SMTP

Il bridge SMTP collega a Notifuse le applicazioni SaaS che offrono solo un'integrazione SMTP (come Supabase Auth, Firebase o Auth0). Le loro email usano così i design e il branding che crei nell'editor MJML di Notifuse, al posto dei template predefiniti del SaaS.

Vedi la [documentazione d'uso del bridge SMTP](https://www.notifuse.com/it/docs/features/transactional-api.md#smtp-bridge) per esempi di invio delle email una volta configurato.

### Modalità TLS

Il bridge supporta tre modalità TLS tramite `SMTP_BRIDGE_TLS`:

| Modalità   | Descrizione                                                                                                                                  | Porta tipica |
| ---------- | -------------------------------------------------------------------------------------------------------------------------------------------- | ------------ |
| `starttls` | Ascolta in chiaro; i client devono passare a TLS con `STARTTLS` prima di `AUTH`. Predefinita quando sono forniti i certificati.              | `587`        |
| `implicit` | TLS dal primo byte (SMTPS). Necessaria per i client che parlano solo TLS implicito.                                                          | `465`        |
| `off`      | Nessun TLS. Sicura solo dietro un reverse proxy che termina il TLS (HAProxy, Caddy layer4, stunnel, nginx Mail, Postfix) su una rete fidata. | qualsiasi    |

Quando `SMTP_BRIDGE_TLS` non è impostata, Notifuse sceglie `starttls` se sono forniti sia il certificato sia la chiave, altrimenti `off` in sviluppo.

> [!WARNING]
>
> In produzione (`ENVIRONMENT=production`) il bridge non parte senza TLS configurato. Fornisci `SMTP_BRIDGE_TLS_CERT_BASE64` e `SMTP_BRIDGE_TLS_KEY_BASE64`, oppure imposta esplicitamente `SMTP_BRIDGE_TLS=off` se lavori dietro un reverse proxy che termina il TLS.

### Configurazione di produzione con Let's Encrypt

In produzione, usa certificati TLS validi di Let's Encrypt, ottenuti con certbot e una challenge DNS.

#### Passo 1: installare Certbot

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

# macOS
brew install certbot

# CentOS/RHEL
sudo yum install certbot
```

#### Passo 2: generare il certificato con una challenge DNS

Conviene usare una challenge DNS: non richiede le porte 80 o 443 aperte e funziona anche se il tuo server SMTP usa un'altra porta.

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

Certbot ti chiede poi di creare un record 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
```

#### Passo 3: aggiungere il record DNS TXT

Aggiungi il record TXT presso il tuo provider DNS:

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

Attendi qualche minuto per la propagazione DNS, poi controlla il record:

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

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

Quando il record è verificato, premi Invio in certbot per continuare.

#### Passo 4: codificare i certificati in Base64

Quando certbot ha generato i certificati, codificali in 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
```

#### Passo 5: aggiungere le variabili d'ambiente

Copia i valori codificati in base64 nel tuo file `.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 configura un cron job per il rinnovo. Dopo ogni rinnovo, ricodifica i certificati in base64
> e aggiorna le variabili d'ambiente.

### Configurazione di sviluppo con certificati autofirmati

Per lo sviluppo in locale puoi usare certificati autofirmati:

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

**Attenzione**: i certificati autofirmati servono solo per lo sviluppo. Non usarli mai in produzione.

## Gestione della configurazione

La procedura guidata di configurazione va bene per deployment rapidi e test: salva la configurazione in modo sicuro nel database e la gestisci dall'interfaccia web. In produzione sono consigliate le variabili d'ambiente, che proteggono meglio i dati sensibili e lasciano la configurazione alla tua pipeline di deployment. Quando sono impostate entrambe, vince sempre la variabile d'ambiente.

In produzione consigliamo le variabili d'ambiente per la configurazione sensibile (credenziali SMTP, SECRET_KEY) e la procedura guidata o l'interfaccia di amministrazione per il resto (endpoint API, ecc.).

## Autenticazione programmatica

Per le pipeline CI/CD e i deployment automatizzati, un utente root può autenticarsi in modo programmatico con una firma HMAC-SHA256 invece di un magic link. Quando `ROOT_EMAIL` elenca più indirizzi, usane uno qualsiasi come `ROOT_EMAIL` qui sotto: l'email firmata deve corrispondere esattamente a una delle email root configurate.

```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 restituisce un token JWT per le richieste API successive. I timestamp devono discostarsi al massimo di 60 secondi dall'ora del server, e le richieste sono limitate a 5 tentativi ogni 5 minuti.

## Piattaforme di hosting di terze parti

Notifuse è disponibile anche sulle seguenti piattaforme di terze parti.

> [!WARNING]
>
> Queste piattaforme non sono supportate ufficialmente e spesso eseguono versioni vecchie di Notifuse. Per l'ultima versione, gli aggiornamenti automatici e il supporto ufficiale, usa [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)
