Zum Inhalt springen

Self-Hosting

Self-Hosted-Installation

So hosten Sie Notifuse selbst

Tipp

Sie suchen eine verwaltete Lösung? Notifuse Cloud übernimmt Hosting, Sicherheit, Backups, Updates und Wartung, ab 16 $/Monat.

Erste Schritte

Notifuse enthält einen interaktiven Einrichtungsassistenten. Viele Umgebungsvariablen sind optional und lassen sich beim ersten Start in der Weboberfläche festlegen.

Der ausgefüllte Einrichtungsassistent: Administrator, Versand der System-E-Mails (SMTP), Updates und Telemetrie, Single Sign-on und SMTP-Bridge, daneben die noch offenen Angaben

Schnellstart mit dem Einrichtungsassistenten

  1. Stellen Sie Notifuse mit einer der folgenden Optionen bereit
  2. Öffnen Sie Ihre Instanz im Webbrowser
  3. Füllen Sie den Einrichtungsassistenten aus:
    • Geben Sie die E-Mail-Adresse des Root-Administrators ein (eine oder mehrere)
    • Prüfen Sie den API-Endpunkt, der mit der Adresse der Seite vorausgefüllt ist
    • Richten Sie den SMTP-Server ein, der Anmeldecodes und Einladungen verschickt, und testen Sie die Verbindung
    • Lassen Sie die Update-Prüfung und die anonyme Telemetrie eingeschaltet oder schalten Sie sie ab (beide sind standardmäßig aktiv)
    • Richten Sie bei Bedarf Single Sign-on (OpenID Connect) und die SMTP-Bridge ein
  4. Arbeiten Sie mit Notifuse.

Eine Einstellung, die bereits über eine Umgebungsvariable gesetzt ist, erscheint im Assistenten gesperrt, zusammen mit dem Namen der Variablen. Der Assistent fragt sie nicht ab.

compose.yaml startet Notifuse mit einem eigenen PostgreSQL 18. Die Datei funktioniert für sich allein: Der Server braucht keinen Klon des Repositorys, nur Docker Engine 25.0 und Compose v2.24 oder neuer (docker compose version).

Warnung

Diese Schritte richten eine neue Installation ein. Um eine laufende Installation zu aktualisieren, behalten Sie ihre .env und den darin enthaltenen SECRET_KEY, denn ein neuer Schlüssel allein macht Ihre gespeicherten Daten unlesbar (siehe Aktualisieren). Eine Installation, die vor Version 42.0 aus compose.yaml ohne gesetzten SECRET_KEY gestartet wurde, läuft mit einem Standardwert, den Notifuse inzwischen ablehnt: Unter Geheimen Schlüssel ersetzen finden Sie diesen Wert und die nötige Änderung.

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

Damit läuft Notifuse auf Port 8081, und PostgreSQL ist nur vom Server selbst aus erreichbar (127.0.0.1:5433). Beim ersten Start führt Sie der Einrichtungsassistent durch die Konfiguration. Sie können auch Umgebungsvariablen in der Datei .env setzen: Notifuse erhält jede Variable aus dieser Datei.

Notifuse liefert nur HTTP ohne Verschlüsselung aus. Schalten Sie einen Reverse Proxy mit TLS davor, bevor Sie eine Domain darauf zeigen lassen, und setzen Sie HTTP_BIND=127.0.0.1 in .env, wenn dieser Proxy auf demselben Server läuft.

Warnung

Compose benennt das Datenbank-Volume nach dem Verzeichnis, das compose.yaml enthält (hier notifuse_postgres-data). Behalten Sie diesen Verzeichnisnamen bei: In einem umbenannten oder verschobenen Verzeichnis startet docker compose up -d eine neue Installation mit leerer Datenbank. docker compose down -v löscht die Datenbank.

Eine Docker-Compose-Installation aktualisieren

Lesen Sie die Einträge im Changelog zwischen Ihrer Version und der neuen und erstellen Sie ein Backup. Laden Sie dann die compose.yaml des neuen Release herunter und überschreiben Sie damit Ihre (oder setzen Sie NOTIFUSE_VERSION=v44.0 in .env, um das Release zu wählen), und führen Sie docker compose up -d aus.

Mit Version 44.0 wechselt compose.yaml auf PostgreSQL 18: Das erste docker compose up -d kopiert Ihre PostgreSQL-17-Daten in ein zweites Volume und aktualisiert sie dann. PostgreSQL aktualisieren erklärt, was dabei passiert, wie Sie das Ergebnis prüfen und wie Sie zurückkehren.

Aus einem Klon des Repositorys

In einem Klon baut dieselbe Datei Notifuse aus dem Quellcode: mit docker compose up -d --build, oder mit docker compose watch, um bei jeder Änderung neu zu bauen. Ohne --build startet sie das Image, das für das in der Datei genannte Release veröffentlicht wurde. Ein noch nicht veröffentlichtes Release auf dem Branch dev wird aus dem Checkout gebaut. Bis Version 43 hat compose.yaml immer aus dem Checkout gebaut.

Option 2: Eigenständiges Docker-Image (Produktion)

Für den Produktivbetrieb verwenden Sie das eigenständige Docker-Image mit Ihrer eigenen PostgreSQL-Datenbank:

# 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

Beim ersten Start führt Sie der Einrichtungsassistent durch die Konfiguration. Sie können auch Umgebungsvariablen setzen.

PostgreSQL-Datenbank (nur Option 2)

Mit dem eigenständigen Docker-Image können Sie jede PostgreSQL-Datenbank mit Root-Zugangsdaten verwenden. Notifuse legt seine eigene Systemdatenbank an.

Version: PostgreSQL 17 oder neuer (auf einem älteren Server startet Notifuse nicht); compose.yaml bringt PostgreSQL 18 mit

Notifuse legt für jeden Arbeitsbereich eine eigene Datenbank an, um Probleme mit mehreren Mandanten in einer Datenbank zu vermeiden. Deshalb braucht es Root-Zugangsdaten.

Hinweis: Docker Compose enthält PostgreSQL, dort entfällt dieser Abschnitt.

Ein SMTP-Server

Notifuse braucht einen SMTP-Server, um System-E-Mails zu verschicken, etwa Anmeldecodes und Einladungs-E-Mails.

Bei SES erstellen Sie SMTP-Zugangsdaten im Bereich SMTP settings des SES-Dashboards.

Ein öffentlicher API-Endpunkt

Notifuse braucht einen öffentlichen API-Endpunkt, der aus dem Internet erreichbar ist, zum Beispiel https://emails.yourcompany.com.

Hinter einem Reverse Proxy leiten Sie den ursprünglichen Host-Header an Notifuse weiter oder setzen X-Forwarded-Host auf diesen Wert. Webversionen von E-Mails öffnen sich nur auf der Domain, mit der ihr Link verschickt wurde, und auf API_ENDPOINT. Ein Proxy, der Host durch seine Upstream-Adresse ersetzt und kein X-Forwarded-Host setzt, macht alle Webversionen unerreichbar. Ersetzt er ihn durch den Host von API_ENDPOINT, zeigt jede benutzerdefinierte Domain die Webversionen aller Arbeitsbereiche an.

Umgebungsvariablen

Mit dem Einrichtungsassistenten sind viele Umgebungsvariablen optional und lassen sich in der Weboberfläche festlegen. Eine gesetzte Umgebungsvariable hat immer Vorrang vor der Einstellung in der Datenbank.

Warnung

Sonderzeichen in .env-Dateien

In einer .env-Datei muss ein Wert, der das Zeichen # enthält (häufig in Passwörtern), in Anführungszeichen stehen:

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

Das gilt nur für .env-Dateien, nicht für Variablen, die Sie direkt in Ihrer Shell, in Docker Compose oder in einer Plattform zur Container-Orchestrierung setzen.

Erforderliche Variablen

VariableBeschreibung
DB_HOSTPostgreSQL-Host (z. B. localhost oder db.yourcompany.com)
DB_PORTPostgreSQL-Port (z. B. 5432)
DB_USERBenutzername der Datenbank (z. B. postgres)
DB_PASSWORDPasswort der Datenbank (z. B. postgres)
SECRET_KEYGeheimer Schlüssel zum Verschlüsseln und Signieren (mit dem Befehl unten erzeugen)

SECRET_KEY erzeugen:

openssl rand -base64 32

Notifuse startet nicht mit einem SECRET_KEY, der weniger als 32 Byte ergibt.

Warnung

Ersetzen Sie Ihren SECRET_KEY nie einfach durch einen neuen Wert. Er verschlüsselt alle Integrationsgeheimnisse der Arbeitsbereiche (API-Schlüssel von E-Mail-Anbietern, SMTP-Passwörter usw.), die ein neuer Schlüssel allein nicht lesen kann. Um ihn zu ändern, folgen Sie Geheimen Schlüssel ersetzen.

Geheimen Schlüssel ersetzen

SECRET_KEY kann mehrere Schlüssel enthalten, durch Kommas getrennt (ein Komma, das zu einem Schlüssel gehört, wird doppelt geschrieben). Der erste Schlüssel verschlüsselt und signiert; mit den anderen liest Notifuse nur die Daten, die mit ihnen gespeichert wurden.

Startet Notifuse mit einer Liste, verschlüsselt es diese Daten in einer einzigen Transaktion mit dem ersten Schlüssel neu, bevor es irgendetwas ausliefert. So ersetzen Sie Ihren Schlüssel:

  1. Erzeugen Sie mit openssl rand -base64 32 einen neuen Schlüssel.
  2. Setzen Sie ihn an die erste Stelle und Ihren aktuellen Schlüssel dahinter: SECRET_KEY=<new key>,<current key>. Enthält Ihr aktueller Schlüssel ein Komma, schreiben Sie dieses Komma doppelt. Beginnt oder endet er mit einem Komma, setzen Sie ein Leerzeichen zwischen dieses und das Komma, das die Schlüssel trennt (SECRET_KEY=<new key>, ,,<rest of the key>). Eine Version vor 42.0 liest die ganze Liste als einen einzigen Schlüssel: Setzen Sie die Liste deshalb im selben Schritt wie das Update auf 42.0.
  3. Stoppen Sie alle Notifuse-Instanzen und starten Sie dann alle mit diesem Wert. Eine Instanz, die noch nur mit dem aktuellen Schlüssel läuft, kann die von den anderen neu verschlüsselten Daten nicht lesen. Umgekehrt kann eine Instanz mit der Liste das, was eine solche Instanz schreibt, erst nach dem nächsten Start mit der Liste lesen.
  4. Sobald alle Instanzen mit diesem Wert laufen, setzen Sie SECRET_KEY auf den neuen Schlüssel allein, ohne Anführungszeichen oder Leerzeichen drumherum: Ein einzelner Schlüssel wird genau so verwendet, wie er geschrieben ist. Öffnet er keinen der gespeicherten Arbeitsbereiche (oder, solange keiner gespeichert ist, keine der verschlüsselten Systemeinstellungen), startet Notifuse nicht.

Lässt sich der Schlüssel eines Arbeitsbereichs oder eine von ihm genutzte Zugangsangabe mit keinem der aufgeführten Schlüssel öffnen, startet Notifuse nicht, ändert nichts und nennt diesen Arbeitsbereich. Eine verschlüsselte Systemeinstellung, die keiner von ihnen öffnet (SMTP-Zugangsdaten oder das OIDC-Client-Secret aus dem Einrichtungsassistenten, Zertifikat oder Schlüssel für das TLS der SMTP-Bridge), bleibt unverändert und wird in einer Warnung in den Startprotokollen genannt. Notifuse läuft dann ohne sie; um sie zu behalten, nehmen Sie den Schlüssel in die Liste auf, mit dem sie verschlüsselt ist. Notifuse startet nicht und nennt die Einstellung, wenn Single Sign-on oder die SMTP-Bridge aktiv ist und sie braucht, oder wenn noch kein Arbeitsbereich gespeichert ist und sich keine dieser Einstellungen öffnen lässt.

Nach dem Ersetzen des Schlüssels sind alle abgemeldet. API-Schlüssel müssen gelöscht und neu erstellt, ausstehende Einladungen erneut verschickt werden, und Skripte, die user.rootSignin aufrufen, signieren mit dem neuen Schlüssel. Ein API-Client, der eine Integration mit den verschlüsselten Zugangsdaten speichert, die er vor der Änderung gelesen hat, wird abgewiesen, bis er den Arbeitsbereich neu liest. Datenbank-Backups von vor der Änderung brauchen weiterhin den früheren Schlüssel. Daten in der Datenbank eines Arbeitsbereichs, etwa der Nachrichtenverlauf, sind mit dem eigenen Schlüssel dieses Arbeitsbereichs verschlüsselt und nicht betroffen.

Warnung

Vor Version 42.0 lieferte compose.yaml einen Standard-SECRET_KEY mit und env.example einen Platzhalter. Notifuse startet nicht, wenn der erste Schlüssel von SECRET_KEY einer dieser Werte ist oder weniger als 32 Byte ergibt, und liest ein einzelnes Komma als Trennzeichen zwischen Schlüsseln: Enthält Ihr Schlüssel ein Komma, schreiben Sie beim Update jedes seiner Kommas doppelt. Läuft Ihre Installation mit einem dieser Werte, ersetzen Sie ihn wie oben beschrieben und lassen ihn hinter dem neuen Schlüssel stehen, im selben Schritt wie das Update auf 42.0. Wenn Sie aus compose.yaml gestartet haben, ohne SECRET_KEY zu setzen, ist Ihr aktueller Schlüssel der frühere Standardwert:

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

Anwendungsvariablen (optional mit dem Einrichtungsassistenten)

Setzen Sie diese beim ersten Start im Einrichtungsassistenten oder als Umgebungsvariablen. Umgebungsvariablen haben immer Vorrang vor dem Assistenten.

VariableBeschreibung
ROOT_EMAILE-Mail-Adresse des Root-Administrators (z. B. admin@yourcompany.com). Nimmt mehrere durch Komma oder Semikolon getrennte Adressen an, um mehreren Administratoren Root-Rechte zu geben (z. B. alice@yourcompany.com,bob@yourcompany.com); der Abgleich unterscheidet Groß- und Kleinschreibung.
API_ENDPOINTURL des öffentlichen API-Endpunkts (z. B. https://emails.yourcompany.com). Wie Sie später auf eine andere Domain umziehen, steht unter Domain ändern.
SMTP_HOSTHost des SMTP-Servers (z. B. smtp.gmail.com)
SMTP_PORTPort des SMTP-Servers (z. B. 587 oder 465)
SMTP_USERNAMESMTP-Benutzername (z. B. noreply@yourcompany.com)
SMTP_PASSWORDSMTP-Passwort (z. B. your_smtp_password)
SMTP_FROM_EMAILAbsenderadresse (z. B. noreply@yourcompany.com)
SMTP_FROM_NAMEAbsendername (z. B. Your Company Name)
SMTP_EHLO_HOSTNAMEEigener EHLO-Hostname für SMTP-Verbindungen (z. B. mail.yourdomain.com). Ist er leer, wird der SMTP-Host verwendet. Hilfreich, wenn SMTP-Server EHLO localhost ablehnen.

Hinweis

Mehrere Root-Benutzer: ROOT_EMAIL kann mehr als eine E-Mail-Adresse enthalten (durch Komma oder Semikolon getrennt). So kann eine gemeinsam genutzte Instanz mehrere Administratoren mit Root-Rechten haben: Arbeitsbereiche anlegen, die Systemeinstellungen öffnen und sich programmatisch authentifizieren. Notifuse legt beim Start für jede aufgeführte Adresse ein Benutzerkonto an, damit sich jeder Root-Benutzer sofort anmelden kann. Der Abgleich unterscheidet Groß- und Kleinschreibung, und eine einzelne Adresse verhält sich genau wie bisher. Der Einrichtungsassistent legt den ersten (primären) Root-Benutzer fest; weitere fügen Sie dort als Liste hinzu oder über die Umgebungsvariable ROOT_EMAIL.

Optionale Variablen

VariableBeschreibungStandard
Serverkonfiguration
SERVER_PORTPort, auf dem der Server lauscht (z. B. 8080)8080
SERVER_HOSTHostadresse, an die der Server gebunden wird (z. B. 0.0.0.0)0.0.0.0
CORS_ALLOW_ORIGINOrigins, die die API aus einem Browser aufrufen dürfen: *, ein einzelner Origin oder eine kommagetrennte Liste (z. B. https://yourapp.com,https://admin.yourapp.com; Listen erfordern 41.1 oder neuer). Ein eingeschränkter Wert muss jede benutzerdefinierte Domain der Arbeitsbereiche enthalten, denn deren Konsole und Benachrichtigungscenter rufen die API von ihrem eigenen Origin aus auf.*
ENVIRONMENTUmgebungsmodus (z. B. production)production
LOG_LEVELLog-Level (z. B. debug oder warn)info
Datenbankkonfiguration
DB_PREFIXNamenspräfix für die System- und Arbeitsbereichsdatenbanken (z. B. notifuse für notifuse_system und notifuse_ws_*)notifuse
DB_NAMEName der Datenbank (z. B. notifuse_system)${DB_PREFIX}_system
DB_SSLMODESSL-Modus der Datenbank (z. B. require oder disable)require
DB_EXPECT_EXISTINGMit true legt Notifuse die Systemdatenbank weder an noch initialisiert es sie, und es legt keine fehlende Arbeitsbereichsdatenbank an. Setzen Sie die Variable auf einem Server, der die Daten bereits enthalten muss (nach einem Update oder einer Wiederherstellung): Bei einem leeren PostgreSQL hält Notifuse dann an, statt eine neue Installation zu startenfalse
DB_MAX_CONNECTIONSMaximale Gesamtzahl an Verbindungen über alle Datenbanken (z. B. 100)100
DB_MAX_CONNECTIONS_PER_DBMaximale Verbindungen pro Arbeitsbereichsdatenbank (z. B. 3)3
DB_CONNECTION_MAX_LIFETIMEMaximale Lebensdauer einer Verbindung (z. B. 10m)10m
DB_CONNECTION_MAX_IDLE_TIMEMaximale Leerlaufzeit, bevor eine Verbindung geschlossen wird (z. B. 5m)5m
Konfiguration des Task-Schedulers
TASK_SCHEDULER_ENABLEDInternen Task-Scheduler aktivieren (z. B. true oder false)true
TASK_SCHEDULER_INTERVALIntervall der Aufgabenausführung in Sekunden (z. B. 30)30
TASK_SCHEDULER_MAX_TASKSMaximale Anzahl gleichzeitiger Aufgaben (z. B. 10)10
Kampagnenkonfiguration
BROADCAST_DATA_FEED_ALLOW_PRIVATE_HOSTSErlaubt Daten-Feeds von Kampagnen den Abruf von privaten, Loopback- und Link-Local-Adressen. Das deaktiviert den SSRF-Schutz für Daten-Feed-Anfragen: Aktivieren Sie es nur in vertrauenswürdigen Umgebungen, die Feeds bewusst aus Ihrem internen Netzwerk abrufen (z. B. true).false
EMAIL_QUEUE_CONCURRENCYAnzahl der E-Mails, die jede E-Mail-Integration außer SMTP pro Notifuse-Instanz gleichzeitig für Kampagnen und Automatisierungen versendet, zwischen 1 und 50 (z. B. 20; 42.0 oder neuer). Siehe Versandgeschwindigkeit.10
EMAIL_QUEUE_SMTP_CONCURRENCYDasselbe für SMTP-Integrationen, zwischen 1 und 50 (42.0 oder neuer). Erhöhen Sie den Wert nur, wenn Ihr SMTP-Server mehrere Verbindungen gleichzeitig annimmt (z. B. 4).1
Webhook-Konfiguration
WEBHOOK_DELIVERY_ALLOW_PRIVATE_HOSTSErlaubt ausgehenden Webhooks (Webhook-Abonnements und Webhook-Knoten in Automatisierungen), private, Loopback- und Link-Local-Adressen zu erreichen. Das deaktiviert den SSRF-Schutz für sie: Aktivieren Sie es nur in vertrauenswürdigen Umgebungen, die Webhooks bewusst in Ihr internes Netzwerk zustellen, etwa an n8n im selben Docker-Netzwerk (z. B. true). Solange die Variable aus ist, verbinden sich ausgehende Webhooks direkt und ignorieren HTTP_PROXY/HTTPS_PROXY.false
Lizenz
NOTIFUSE_LICENSE_KEYEin Lizenzschlüssel für Self-Hosting. Hat Vorrang vor einem in der Konsole eingefügten Schlüssel. Für den Betrieb von Notifuse nicht nötig.-
Datenschutzeinstellungen
TELEMETRYAnonyme Nutzungsstatistiken senden (z. B. true oder false)true
CHECK_FOR_UPDATESNach neuen Versionen suchen (z. B. true oder false)true
SMTP-Bridge-Konfiguration
SMTP_BRIDGE_ENABLEDSMTP-Bridge-Server für transaktionale E-Mails aktivieren (z. B. true oder false)false
SMTP_BRIDGE_PORTPort der SMTP-Bridge (z. B. 587 für STARTTLS, 465 für implizites TLS)587
SMTP_BRIDGE_DOMAINÖffentlicher Domainname der SMTP-Bridge (z. B. smtp.yourdomain.com)localhost
SMTP_BRIDGE_TLSTLS-Modus: starttls, implicit oder off (siehe unten). Wird automatisch bestimmt, wenn die Variable nicht gesetzt ist.automatisch
SMTP_BRIDGE_TLS_CERT_BASE64Base64-kodiertes TLS-Zertifikat (erforderlich für starttls und implicit)-
SMTP_BRIDGE_TLS_KEY_BASE64Base64-kodierter privater TLS-Schlüssel (erforderlich für starttls und implicit)-
Single Sign-on (OIDC) (siehe SSO-Anleitung)
OIDC_ENABLEDSingle Sign-on über OpenID Connect aktivieren (z. B. true oder false)false
OIDC_ISSUER_URLIssuer-URL des IdP, muss https verwenden (z. B. https://accounts.google.com)-
OIDC_CLIENT_IDOAuth2-Client-ID von Ihrem Identitätsanbieter-
OIDC_CLIENT_SECRETOAuth2-Client-Secret (verschlüsselt gespeichert; wird nie an den Browser gesendet)-
OIDC_REDIRECT_URIBeim IdP registrierte Callback-URL. Wird aus API_ENDPOINT abgeleitet, wenn leer.<API_ENDPOINT>/api/user.oidc.callback
OIDC_SCOPESDurch Leerzeichen getrennte Scopes (openid ist immer enthalten)openid email profile
OIDC_BUTTON_LABELBeschriftung der AnmeldeschaltflächeSign in with SSO
OIDC_AUTO_CREATE_USERSKonten bei der ersten SSO-Anmeldung automatisch anlegen (erfordert OIDC_ALLOWED_DOMAINS)false
OIDC_ALLOWED_DOMAINSDurch Komma oder Semikolon getrennte Liste der E-Mail-Domains, für die Konten automatisch angelegt werden dürfen-
Tracing-Konfiguration
TRACING_ENABLEDTracing aktivieren (z. B. true)false
TRACING_SERVICE_NAMEDienstname für das Tracing (z. B. notifuse-production)notifuse-api
TRACING_SAMPLING_PROBABILITYSampling-Wahrscheinlichkeit (z. B. 0.05)0.1
TRACING_TRACE_EXPORTERTrace-Exporter: jaeger/zipkin/stackdriver/datadog/xray/none (z. B. jaeger oder datadog)none
TRACING_JAEGER_ENDPOINTJaeger-Endpunkt (z. B. http://jaeger:14268/api/traces)http://localhost:14268/api/traces
TRACING_ZIPKIN_ENDPOINTZipkin-Endpunkt (z. B. http://zipkin:9411/api/v2/spans)http://localhost:9411/api/v2/spans
TRACING_STACKDRIVER_PROJECT_IDStackdriver-Projekt-ID (z. B. my-gcp-project-id)-
TRACING_AZURE_INSTRUMENTATION_KEYInstrumentierungsschlüssel für Azure Monitor (z. B. 12345678-1234-1234-1234-123456789012)-
TRACING_DATADOG_AGENT_ADDRESSAdresse des Datadog-Agents (z. B. datadog-agent:8126)localhost:8126
TRACING_DATADOG_API_KEYDatadog-API-Schlüssel (z. B. 1234567890abcdef1234567890abcdef)-
TRACING_XRAY_REGIONAWS-X-Ray-Region (z. B. us-east-1)us-west-2
TRACING_AGENT_ENDPOINTAllgemeiner Agent-Endpunkt (z. B. monitoring-agent:8126)localhost:8126
TRACING_METRICS_EXPORTERMetrik-Exporter: stackdriver/prometheus/datadog/none (z. B. prometheus)none
TRACING_PROMETHEUS_PORTPort für Prometheus-Metriken (z. B. 9464)9464

SMTP-Bridge-Konfiguration

Die SMTP-Bridge verbindet SaaS-Anwendungen, die nur eine SMTP-Integration anbieten (etwa Supabase Auth, Firebase oder Auth0), mit Notifuse. Deren E-Mails verwenden dann die Designs und das Branding aus dem MJML-Editor von Notifuse statt der Standardvorlagen des SaaS-Dienstes.

Beispiele für den E-Mail-Versand nach der Einrichtung finden Sie in der Dokumentation zur SMTP-Bridge.

TLS-Modi

Die Bridge kennt über SMTP_BRIDGE_TLS drei TLS-Modi:

ModusBeschreibungTypischer Port
starttlsLauscht im Klartext; Clients müssen vor AUTH per STARTTLS auf TLS umschalten. Standard, wenn Zertifikate vorhanden sind.587
implicitTLS ab dem ersten Byte (SMTPS). Erforderlich für Clients, die nur implizites TLS beherrschen.465
offKein TLS. Nur sicher hinter einem Reverse Proxy, der TLS terminiert (HAProxy, Caddy layer4, stunnel, nginx Mail, Postfix), in einem vertrauenswürdigen Netzwerk.beliebig

Ist SMTP_BRIDGE_TLS nicht gesetzt, wählt Notifuse starttls, wenn Zertifikat und Schlüssel vorhanden sind, andernfalls in der Entwicklungsumgebung off.

Warnung

In Produktion (ENVIRONMENT=production) startet die Bridge nicht ohne TLS-Konfiguration. Geben Sie SMTP_BRIDGE_TLS_CERT_BASE64 und SMTP_BRIDGE_TLS_KEY_BASE64 an, oder setzen Sie ausdrücklich SMTP_BRIDGE_TLS=off, wenn ein Reverse Proxy davor das TLS terminiert.

Einrichtung für die Produktion mit Let’s Encrypt

Verwenden Sie in Produktion gültige TLS-Zertifikate von Let’s Encrypt, die Sie mit certbot und einer DNS-Challenge beziehen.

Schritt 1: Certbot installieren

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

# macOS
brew install certbot

# CentOS/RHEL
sudo yum install certbot

Schritt 2: Zertifikat mit DNS-Challenge erzeugen

Wir empfehlen eine DNS-Challenge: Dafür müssen weder Port 80 noch Port 443 offen sein, und sie funktioniert auch, wenn Ihr SMTP-Server auf einem anderen Port läuft.

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

Certbot fordert Sie dann auf, einen DNS-TXT-Eintrag anzulegen:

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

Schritt 3: DNS-TXT-Eintrag hinzufügen

Legen Sie den TXT-Eintrag bei Ihrem DNS-Anbieter an:

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

Warten Sie einige Minuten, bis sich der DNS-Eintrag verbreitet hat, und prüfen Sie ihn dann:

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

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

Sobald der Eintrag bestätigt ist, drücken Sie in certbot die Eingabetaste, um fortzufahren.

Schritt 4: Zertifikate in Base64 kodieren

Sobald certbot die Zertifikate erzeugt hat, kodieren Sie sie 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

Schritt 5: In die Umgebungsvariablen eintragen

Kopieren Sie die Base64-Werte in Ihre .env-Datei:

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

Hinweis

Certbot richtet einen Cron-Job für die Erneuerung ein. Kodieren Sie die Zertifikate nach jeder Erneuerung erneut in Base64 und aktualisieren Sie Ihre Umgebungsvariablen.

Einrichtung für die Entwicklung mit selbstsignierten Zertifikaten

Für die lokale Entwicklung können Sie selbstsignierte Zertifikate verwenden:

# 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

Warnung: Selbstsignierte Zertifikate sind nur für die Entwicklung gedacht. Verwenden Sie sie nie in Produktion.

Konfiguration verwalten

Der Einrichtungsassistent eignet sich für schnelle Deployments und Tests: Er speichert die Konfiguration sicher in der Datenbank, und Sie verwalten sie in der Weboberfläche. In Produktion empfehlen sich Umgebungsvariablen, denn sie schützen sensible Daten besser und lassen Ihre Deployment-Pipeline die Konfiguration verwalten. Sind beide gesetzt, gewinnt immer die Umgebungsvariable.

In Produktion empfehlen wir Umgebungsvariablen für sensible Konfiguration (SMTP-Zugangsdaten, SECRET_KEY) und den Einrichtungsassistenten oder die Admin-Oberfläche für den Rest (API-Endpunkt usw.).

Programmatische Authentifizierung

Für CI/CD-Pipelines und automatisierte Deployments kann sich ein Root-Benutzer programmatisch mit einer HMAC-SHA256-Signatur authentifizieren, statt einen Magic Link zu verwenden. Wenn ROOT_EMAIL mehrere Adressen enthält, setzen Sie unten eine beliebige davon als ROOT_EMAIL ein: Die signierte E-Mail-Adresse muss genau einer der konfigurierten Root-Adressen entsprechen.

#!/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}\"}"

Der Endpunkt gibt ein JWT-Token für die folgenden API-Anfragen zurück. Zeitstempel dürfen höchstens 60 Sekunden von der Serverzeit abweichen, und Anfragen sind auf 5 Versuche pro 5 Minuten begrenzt.

Hosting-Plattformen von Drittanbietern

Notifuse ist auch auf den folgenden Plattformen von Drittanbietern verfügbar.

Warnung

Diese Plattformen werden nicht offiziell unterstützt und laufen oft mit veralteten Versionen von Notifuse. Für die neueste Version, automatische Updates und offiziellen Support nutzen Sie Notifuse Cloud.