Vai al contenuto

Self-hosting

Installazione self-hosted

Come installare Notifuse sul tuo server

Suggerimento

Cerchi una soluzione gestita? Notifuse Cloud 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

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.

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

Attenzione

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). 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 riporta quel valore e la modifica da fare.

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

Attenzione

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 tra la tua versione e quella nuova, fai un backup, 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 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:

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

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

Attenzione

Caratteri speciali nei file .env

In un file .env, un valore che contiene il carattere # (frequente nelle password) deve stare tra virgolette:

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

VariabileDescrizione
DB_HOSTHost di PostgreSQL (es. localhost o db.yourcompany.com)
DB_PORTPorta di PostgreSQL (es. 5432)
DB_USERNome utente del database (es. postgres)
DB_PASSWORDPassword del database (es. postgres)
SECRET_KEYChiave segreta per cifratura e firma (generala con il comando qui sotto)

Genera la SECRET_KEY:

openssl rand -base64 32

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

Attenzione

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.

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.

Attenzione

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:

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

VariabileDescrizione
ROOT_EMAILEmail 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_ENDPOINTURL pubblico dell’endpoint API (es. https://emails.yourcompany.com). Per passare in seguito a un altro dominio, vedi Cambiare dominio.
SMTP_HOSTHost del server SMTP (es. smtp.gmail.com)
SMTP_PORTPorta del server SMTP (es. 587 o 465)
SMTP_USERNAMENome utente SMTP (es. noreply@yourcompany.com)
SMTP_PASSWORDPassword SMTP (es. your_smtp_password)
SMTP_FROM_EMAILIndirizzo del mittente (es. noreply@yourcompany.com)
SMTP_FROM_NAMENome del mittente (es. Your Company Name)
SMTP_EHLO_HOSTNAMEHostname EHLO personalizzato per le connessioni SMTP (es. mail.yourdomain.com). Se vuoto, usa l’host SMTP. Utile quando i server SMTP rifiutano EHLO localhost.

Nota

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

VariabileDescrizionePredefinito
Configurazione del server
SERVER_PORTPorta su cui il server è in ascolto (es. 8080)8080
SERVER_HOSTIndirizzo host a cui collegarsi (es. 0.0.0.0)0.0.0.0
CORS_ALLOW_ORIGINOrigini 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.*
ENVIRONMENTModalità dell’ambiente (es. production)production
LOG_LEVELLivello di log (es. debug o warn)info
Configurazione del database
DB_PREFIXPrefisso del nome per i database di sistema e dei workspace (es. notifuse per notifuse_system e notifuse_ws_*)notifuse
DB_NAMENome del database (es. notifuse_system)${DB_PREFIX}_system
DB_SSLMODEModalità SSL del database (es. require o disable)require
DB_EXPECT_EXISTINGtrue 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 installazionefalse
DB_MAX_CONNECTIONSNumero massimo di connessioni su tutti i database (es. 100)100
DB_MAX_CONNECTIONS_PER_DBNumero massimo di connessioni per database di workspace (es. 3)3
DB_CONNECTION_MAX_LIFETIMEDurata massima di una connessione (es. 10m)10m
DB_CONNECTION_MAX_IDLE_TIMETempo massimo di inattività prima di chiudere la connessione (es. 5m)5m
Configurazione del task scheduler
TASK_SCHEDULER_ENABLEDAttiva lo scheduler interno dei task (es. true o false)true
TASK_SCHEDULER_INTERVALIntervallo di esecuzione dei task in secondi (es. 30)30
TASK_SCHEDULER_MAX_TASKSNumero massimo di task simultanei (es. 10)10
Configurazione dei broadcast
BROADCAST_DATA_FEED_ALLOW_PRIVATE_HOSTSPermette ai data feed 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_CONCURRENCYEmail 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.10
EMAIL_QUEUE_SMTP_CONCURRENCYLo 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_HOSTSPermette ai webhook in uscita (subscription webhook e nodi webhook delle automazioni) 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_KEYUna chiave di licenza self-hosted. Prevale su una chiave incollata nella console. Non serve per far funzionare Notifuse.-
Impostazioni sulla privacy
TELEMETRYInvia statistiche d’uso anonime (es. true o false)true
CHECK_FOR_UPDATESControlla la disponibilità di nuove versioni (es. true o false)true
Configurazione del bridge SMTP
SMTP_BRIDGE_ENABLEDAttiva il server bridge SMTP per le email transazionali (es. true o false)false
SMTP_BRIDGE_PORTPorta del bridge SMTP (es. 587 per STARTTLS, 465 per TLS implicito)587
SMTP_BRIDGE_DOMAINNome di dominio pubblico del bridge SMTP (es. smtp.yourdomain.com)localhost
SMTP_BRIDGE_TLSModalità TLS: starttls, implicit o off (vedi sotto). Se non è impostata, viene scelta automaticamente.auto
SMTP_BRIDGE_TLS_CERT_BASE64Certificato TLS codificato in Base64 (obbligatorio per starttls e implicit)-
SMTP_BRIDGE_TLS_KEY_BASE64Chiave privata TLS codificata in Base64 (obbligatoria per starttls e implicit)-
Single sign-on (OIDC) (vedi la guida SSO)
OIDC_ENABLEDAttiva il single sign-on tramite OpenID Connect (es. true o false)false
OIDC_ISSUER_URLURL dell’issuer dell’IdP, deve essere https (es. https://accounts.google.com)-
OIDC_CLIENT_IDClient ID OAuth2 del tuo identity provider-
OIDC_CLIENT_SECRETClient secret OAuth2 (cifrato a riposo, mai inviato al browser)-
OIDC_REDIRECT_URIURL di callback registrato presso l’IdP. Se vuoto, è derivato da API_ENDPOINT.<API_ENDPOINT>/api/user.oidc.callback
OIDC_SCOPESScope separati da spazi (openid è sempre incluso)openid email profile
OIDC_BUTTON_LABELTesto del pulsante di accessoSign in with SSO
OIDC_AUTO_CREATE_USERSCrea automaticamente gli account al primo accesso SSO (richiede OIDC_ALLOWED_DOMAINS)false
OIDC_ALLOWED_DOMAINSElenco dei domini email autorizzati, separati da virgole o punti e virgola, che limita la creazione automatica-
Configurazione del tracing
TRACING_ENABLEDAttiva il tracing (es. true)false
TRACING_SERVICE_NAMENome del servizio per il tracing (es. notifuse-production)notifuse-api
TRACING_SAMPLING_PROBABILITYProbabilità di campionamento (es. 0.05)0.1
TRACING_TRACE_EXPORTERExporter delle tracce: jaeger/zipkin/stackdriver/datadog/xray/none (es. jaeger o datadog)none
TRACING_JAEGER_ENDPOINTEndpoint di Jaeger (es. http://jaeger:14268/api/traces)http://localhost:14268/api/traces
TRACING_ZIPKIN_ENDPOINTEndpoint di Zipkin (es. http://zipkin:9411/api/v2/spans)http://localhost:9411/api/v2/spans
TRACING_STACKDRIVER_PROJECT_IDID del progetto Stackdriver (es. my-gcp-project-id)-
TRACING_AZURE_INSTRUMENTATION_KEYChiave di strumentazione di Azure Monitor (es. 12345678-1234-1234-1234-123456789012)-
TRACING_DATADOG_AGENT_ADDRESSIndirizzo dell’agent Datadog (es. datadog-agent:8126)localhost:8126
TRACING_DATADOG_API_KEYAPI key di Datadog (es. 1234567890abcdef1234567890abcdef)-
TRACING_XRAY_REGIONRegione di AWS X-Ray (es. us-east-1)us-west-2
TRACING_AGENT_ENDPOINTEndpoint generico dell’agent (es. monitoring-agent:8126)localhost:8126
TRACING_METRICS_EXPORTERExporter delle metriche: stackdriver/prometheus/datadog/none (es. prometheus)none
TRACING_PROMETHEUS_PORTPorta 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 per esempi di invio delle email una volta configurato.

Modalità TLS

Il bridge supporta tre modalità TLS tramite SMTP_BRIDGE_TLS:

ModalitàDescrizionePorta tipica
starttlsAscolta in chiaro; i client devono passare a TLS con STARTTLS prima di AUTH. Predefinita quando sono forniti i certificati.587
implicitTLS dal primo byte (SMTPS). Necessaria per i client che parlano solo TLS implicito.465
offNessun 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.

Attenzione

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

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

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

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:

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

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

Nota

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:

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

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

Attenzione

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.