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.
Schnellstart mit dem Einrichtungsassistenten
- Stellen Sie Notifuse mit einer der folgenden Optionen bereit
- Öffnen Sie Ihre Instanz im Webbrowser
- 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
- 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.
Option 1: Docker Compose (empfohlen)
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
| Variable | Beschreibung |
|---|---|
DB_HOST | PostgreSQL-Host (z. B. localhost oder db.yourcompany.com) |
DB_PORT | PostgreSQL-Port (z. B. 5432) |
DB_USER | Benutzername der Datenbank (z. B. postgres) |
DB_PASSWORD | Passwort der Datenbank (z. B. postgres) |
SECRET_KEY | Geheimer 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:
- Erzeugen Sie mit
openssl rand -base64 32einen neuen Schlüssel. - 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. - 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.
- Sobald alle Instanzen mit diesem Wert laufen, setzen Sie
SECRET_KEYauf 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.
| Variable | Beschreibung |
|---|---|
ROOT_EMAIL | E-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_ENDPOINT | URL des öffentlichen API-Endpunkts (z. B. https://emails.yourcompany.com). Wie Sie später auf eine andere Domain umziehen, steht unter Domain ändern. |
SMTP_HOST | Host des SMTP-Servers (z. B. smtp.gmail.com) |
SMTP_PORT | Port des SMTP-Servers (z. B. 587 oder 465) |
SMTP_USERNAME | SMTP-Benutzername (z. B. noreply@yourcompany.com) |
SMTP_PASSWORD | SMTP-Passwort (z. B. your_smtp_password) |
SMTP_FROM_EMAIL | Absenderadresse (z. B. noreply@yourcompany.com) |
SMTP_FROM_NAME | Absendername (z. B. Your Company Name) |
SMTP_EHLO_HOSTNAME | Eigener 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
| Variable | Beschreibung | Standard |
|---|---|---|
| Serverkonfiguration | ||
SERVER_PORT | Port, auf dem der Server lauscht (z. B. 8080) | 8080 |
SERVER_HOST | Hostadresse, an die der Server gebunden wird (z. B. 0.0.0.0) | 0.0.0.0 |
CORS_ALLOW_ORIGIN | Origins, 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. | * |
ENVIRONMENT | Umgebungsmodus (z. B. production) | production |
LOG_LEVEL | Log-Level (z. B. debug oder warn) | info |
| Datenbankkonfiguration | ||
DB_PREFIX | Namenspräfix für die System- und Arbeitsbereichsdatenbanken (z. B. notifuse für notifuse_system und notifuse_ws_*) | notifuse |
DB_NAME | Name der Datenbank (z. B. notifuse_system) | ${DB_PREFIX}_system |
DB_SSLMODE | SSL-Modus der Datenbank (z. B. require oder disable) | require |
DB_EXPECT_EXISTING | Mit 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 starten | false |
DB_MAX_CONNECTIONS | Maximale Gesamtzahl an Verbindungen über alle Datenbanken (z. B. 100) | 100 |
DB_MAX_CONNECTIONS_PER_DB | Maximale Verbindungen pro Arbeitsbereichsdatenbank (z. B. 3) | 3 |
DB_CONNECTION_MAX_LIFETIME | Maximale Lebensdauer einer Verbindung (z. B. 10m) | 10m |
DB_CONNECTION_MAX_IDLE_TIME | Maximale Leerlaufzeit, bevor eine Verbindung geschlossen wird (z. B. 5m) | 5m |
| Konfiguration des Task-Schedulers | ||
TASK_SCHEDULER_ENABLED | Internen Task-Scheduler aktivieren (z. B. true oder false) | true |
TASK_SCHEDULER_INTERVAL | Intervall der Aufgabenausführung in Sekunden (z. B. 30) | 30 |
TASK_SCHEDULER_MAX_TASKS | Maximale Anzahl gleichzeitiger Aufgaben (z. B. 10) | 10 |
| Kampagnenkonfiguration | ||
BROADCAST_DATA_FEED_ALLOW_PRIVATE_HOSTS | Erlaubt 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_CONCURRENCY | Anzahl 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_CONCURRENCY | Dasselbe 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_HOSTS | Erlaubt 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_KEY | Ein 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 | ||
TELEMETRY | Anonyme Nutzungsstatistiken senden (z. B. true oder false) | true |
CHECK_FOR_UPDATES | Nach neuen Versionen suchen (z. B. true oder false) | true |
| SMTP-Bridge-Konfiguration | ||
SMTP_BRIDGE_ENABLED | SMTP-Bridge-Server für transaktionale E-Mails aktivieren (z. B. true oder false) | false |
SMTP_BRIDGE_PORT | Port 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_TLS | TLS-Modus: starttls, implicit oder off (siehe unten). Wird automatisch bestimmt, wenn die Variable nicht gesetzt ist. | automatisch |
SMTP_BRIDGE_TLS_CERT_BASE64 | Base64-kodiertes TLS-Zertifikat (erforderlich für starttls und implicit) | - |
SMTP_BRIDGE_TLS_KEY_BASE64 | Base64-kodierter privater TLS-Schlüssel (erforderlich für starttls und implicit) | - |
| Single Sign-on (OIDC) (siehe SSO-Anleitung) | ||
OIDC_ENABLED | Single Sign-on über OpenID Connect aktivieren (z. B. true oder false) | false |
OIDC_ISSUER_URL | Issuer-URL des IdP, muss https verwenden (z. B. https://accounts.google.com) | - |
OIDC_CLIENT_ID | OAuth2-Client-ID von Ihrem Identitätsanbieter | - |
OIDC_CLIENT_SECRET | OAuth2-Client-Secret (verschlüsselt gespeichert; wird nie an den Browser gesendet) | - |
OIDC_REDIRECT_URI | Beim IdP registrierte Callback-URL. Wird aus API_ENDPOINT abgeleitet, wenn leer. | <API_ENDPOINT>/api/user.oidc.callback |
OIDC_SCOPES | Durch Leerzeichen getrennte Scopes (openid ist immer enthalten) | openid email profile |
OIDC_BUTTON_LABEL | Beschriftung der Anmeldeschaltfläche | Sign in with SSO |
OIDC_AUTO_CREATE_USERS | Konten bei der ersten SSO-Anmeldung automatisch anlegen (erfordert OIDC_ALLOWED_DOMAINS) | false |
OIDC_ALLOWED_DOMAINS | Durch Komma oder Semikolon getrennte Liste der E-Mail-Domains, für die Konten automatisch angelegt werden dürfen | - |
| Tracing-Konfiguration | ||
TRACING_ENABLED | Tracing aktivieren (z. B. true) | false |
TRACING_SERVICE_NAME | Dienstname für das Tracing (z. B. notifuse-production) | notifuse-api |
TRACING_SAMPLING_PROBABILITY | Sampling-Wahrscheinlichkeit (z. B. 0.05) | 0.1 |
TRACING_TRACE_EXPORTER | Trace-Exporter: jaeger/zipkin/stackdriver/datadog/xray/none (z. B. jaeger oder datadog) | none |
TRACING_JAEGER_ENDPOINT | Jaeger-Endpunkt (z. B. http://jaeger:14268/api/traces) | http://localhost:14268/api/traces |
TRACING_ZIPKIN_ENDPOINT | Zipkin-Endpunkt (z. B. http://zipkin:9411/api/v2/spans) | http://localhost:9411/api/v2/spans |
TRACING_STACKDRIVER_PROJECT_ID | Stackdriver-Projekt-ID (z. B. my-gcp-project-id) | - |
TRACING_AZURE_INSTRUMENTATION_KEY | Instrumentierungsschlüssel für Azure Monitor (z. B. 12345678-1234-1234-1234-123456789012) | - |
TRACING_DATADOG_AGENT_ADDRESS | Adresse des Datadog-Agents (z. B. datadog-agent:8126) | localhost:8126 |
TRACING_DATADOG_API_KEY | Datadog-API-Schlüssel (z. B. 1234567890abcdef1234567890abcdef) | - |
TRACING_XRAY_REGION | AWS-X-Ray-Region (z. B. us-east-1) | us-west-2 |
TRACING_AGENT_ENDPOINT | Allgemeiner Agent-Endpunkt (z. B. monitoring-agent:8126) | localhost:8126 |
TRACING_METRICS_EXPORTER | Metrik-Exporter: stackdriver/prometheus/datadog/none (z. B. prometheus) | none |
TRACING_PROMETHEUS_PORT | Port 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:
| Modus | Beschreibung | Typischer Port |
|---|---|---|
starttls | Lauscht im Klartext; Clients müssen vor AUTH per STARTTLS auf TLS umschalten. Standard, wenn Zertifikate vorhanden sind. | 587 |
implicit | TLS ab dem ersten Byte (SMTPS). Erforderlich für Clients, die nur implizites TLS beherrschen. | 465 |
off | Kein 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.
