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.
Avvio rapido con la procedura guidata
- Installa Notifuse con una delle opzioni qui sotto
- Apri la tua istanza in un browser
- 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
- 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).
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
| 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:
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:
- Genera una nuova chiave con
openssl rand -base64 32. - 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. - 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.
- Quando tutte le istanze girano con quel valore, imposta
SECRET_KEYsulla 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.
| 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. |
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. |
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
| 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 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. | 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 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_KEY | Una chiave di licenza 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) | ||
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 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.
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.
