Übersicht

Signaturmonster — Dokumentation

Signaturmonster ist ein selbst-gehosteter SMTP-Proxy, der zwischen deinem Mailprogramm (z.B. Thunderbird) und dem ausgehenden Mailserver sitzt. Er fängt jede ausgehende E-Mail ab und reichert sie automatisch mit HTML-Signaturen, Corporate-Identity-Branding und animierten GIF-Bannern an — ohne jede Änderung am Mailprogramm oder am Mailserver.

Architektur

Signaturmonster besteht aus fünf Docker-Containern, die als Compose-Stack betrieben werden:

# Eingehend vom Mailprogramm
Thunderbird / Outlook
       │
       ▼ Port 587
SMTP Proxy       # Python / aiosmtpd — fängt Mails ab, injiziert Signatur
       │
       ▼ intern
Backend API      # FastAPI + SQLite — Signaturen, Regeln, CI-Profile
       │
       ├─ Frontend    # React + nginx — Web-UI auf Port 8080
       │
       └─ Updater     # Prüft ghcr.io auf neue Versionen
       │
       ▼ Weitergeleitet
Echte Mailserver (SMTP, Port 465/587)

Voraussetzungen

Voraussetzungen

Für den Betrieb von Signaturmonster brauchst du:

• Docker ≥ 24 und Docker Compose ≥ 2.20
• Ein Gerät im lokalen Netz mit mindestens 512 MB RAM und Docker-Unterstützung
• Einen ausgehenden SMTP-Server (z.B. Gmail SMTP, Postfix, Hetzner Mail, eigener Server)
• Port 587 auf dem Host frei oder konfigurierbar
• Port 8080 für das Web-UI erreichbar im lokalen Netz (kann geändert werden)

Docker-Version prüfen

docker --version
docker compose version

Installation

Installation

Signaturmonster wird über einen Installer eingerichtet — kein manuelles Klonen, kein Editieren von Konfigurationsdateien. Der Installer prüft Docker, fragt deine SMTP-Zugangsdaten ab, lädt alle nötigen Dateien herunter und startet die Container automatisch.

Linux & macOS

Öffne ein Terminal und führe folgenden Befehl aus:

curl -fsSL https://raw.githubusercontent.com/choldermann/signaturmonster/main/install.sh | bash

Der Installer läuft interaktiv und führt dich Schritt für Schritt durch die Einrichtung. Er funktioniert auf allen gängigen Linux-Distributionen sowie auf macOS. Für Proxmox-LXC, Raspberry Pi oder NAS-Systeme reicht ein einfaches SSH-Terminal.

Windows

Öffne PowerShell als Administrator und führe folgenden Befehl aus:

iex (irm https://raw.githubusercontent.com/choldermann/signaturmonster/main/install.ps1)

Was der Installer einrichtet

Der Installer fragt folgende Werte interaktiv ab:

Danach lädt der Installer docker-compose.yml und nginx.conf direkt von GitHub, schreibt die .env-Datei und startet den Stack mit docker compose pull && docker compose up -d. Ein zufälliger SECRET_KEY wird automatisch generiert.

Am Ende zeigt der Installer die Adressen an:

✓ Signaturmonster läuft!

  Dashboard:  http://192.168.1.42:8080
  SMTP-Port:  192.168.1.42:2587  ← in Thunderbird eintragen

Installation

Proxmox LXC-Container einrichten

Proxmox VE ist eine beliebte Heimserver-Plattform, auf der Signaturmonster besonders gut läuft. Ein LXC-Container ist leichtgewichtiger als eine vollständige VM und teilt sich den Kernel des Hosts — ideal für dauerhaft laufende Dienste. Diese Anleitung führt dich Schritt für Schritt von der Container-Erstellung bis zum laufenden Signaturmonster.

Schritt 1 — LXC-Container erstellen

1. Melde dich im Proxmox-Webinterface an und wähle den gewünschten Node aus
2. Klicke oben rechts auf CT erstellen
3. Allgemein: Vergib eine CT-ID (z.B. 200) und einen aussagekräftigen Hostnamen (z.B. signaturmonster)
4. Template: Wähle ein aktuelles Template — empfohlen ist Debian 12 oder Ubuntu 22.04 LTS. Templates können im Proxmox-Webinterface unter Datacenter → Storage → CT Templates heruntergeladen werden.
5. Festplatte: Mindestens 8 GB — für Docker-Images und die Signaturmonster-Daten reichen 8 GB problemlos aus, 16 GB geben mehr Reserve
6. CPU: Mindestens 1 Core, empfohlen 2 Cores
7. Arbeitsspeicher: Mindestens 512 MB, empfohlen 1024 MB (1 GB) — das gibt dem Docker-Stack komfortabel Luft
8. Netzwerk: Wähle vmbr0 (oder deine LAN-Bridge), stelle DHCP ein oder vergib eine feste IP aus deinem Subnetz. Eine feste IP ist empfohlen, da Thunderbird und andere Clients die Adresse fix eingetragen haben müssen.
9. Klicke auf Fertigstellen — starte den Container noch nicht

Schritt 2 — Nesting aktivieren (für Docker)

Bevor der Container gestartet wird, muss die Nesting-Option aktiviert werden. Ohne sie kann Docker keinen eigenen Netzwerk-Namespace anlegen.

1. Wähle den soeben erstellten Container im Proxmox-Webinterface aus
2. Gehe zu Optionen
3. Doppelklicke auf Funktionen (Features)
4. Aktiviere das Häkchen bei Nesting
5. Optional, aber empfohlen: aktiviere auch FUSE
6. Klicke auf OK

lxc.apparmor.profile: unconfined
features: nesting=1,fuse=1

Schritt 3 — Container starten und Docker installieren

Starte den Container und öffne die Konsole über das Proxmox-Webinterface oder per SSH.

# Paketliste aktualisieren und Abhängigkeiten installieren
apt-get update && apt-get install -y ca-certificates curl gnupg

# Docker-GPG-Schlüssel hinzufügen
install -m 0755 -d /etc/apt/keyrings
curl -fsSL https://download.docker.com/linux/debian/gpg \
  | gpg --dearmor -o /etc/apt/keyrings/docker.gpg
chmod a+r /etc/apt/keyrings/docker.gpg

# Docker-Repository einbinden (Debian 12)
echo \
  "deb [arch=$(dpkg --print-architecture) signed-by=/etc/apt/keyrings/docker.gpg] \
  https://download.docker.com/linux/debian bookworm stable" \
  | tee /etc/apt/sources.list.d/docker.list > /dev/null

# Docker Engine und Compose-Plugin installieren
apt-get update
apt-get install -y docker-ce docker-ce-cli containerd.io \
  docker-buildx-plugin docker-compose-plugin

# Docker-Dienst aktivieren und starten
systemctl enable --now docker

# Versionen prüfen
docker --version
docker compose version

# Paketliste aktualisieren und Abhängigkeiten installieren
apt-get update && apt-get install -y ca-certificates curl gnupg

# Docker-GPG-Schlüssel hinzufügen
install -m 0755 -d /etc/apt/keyrings
curl -fsSL https://download.docker.com/linux/ubuntu/gpg \
  | gpg --dearmor -o /etc/apt/keyrings/docker.gpg
chmod a+r /etc/apt/keyrings/docker.gpg

# Docker-Repository einbinden (Ubuntu 22.04 LTS)
echo \
  "deb [arch=$(dpkg --print-architecture) signed-by=/etc/apt/keyrings/docker.gpg] \
  https://download.docker.com/linux/ubuntu jammy stable" \
  | tee /etc/apt/sources.list.d/docker.list > /dev/null

# Docker Engine und Compose-Plugin installieren
apt-get update
apt-get install -y docker-ce docker-ce-cli containerd.io \
  docker-buildx-plugin docker-compose-plugin

# Docker-Dienst aktivieren und starten
systemctl enable --now docker

# Versionen prüfen
docker --version
docker compose version

Schritt 4 — Signaturmonster installieren

Mit laufendem Docker kann der Signaturmonster-Installer direkt im Container ausgeführt werden:

curl -fsSL https://raw.githubusercontent.com/choldermann/signaturmonster/main/install.sh | bash

Der Installer fragt interaktiv nach deinen SMTP-Zugangsdaten und richtet alles ein. Am Ende werden die Adressen angezeigt, unter denen du das Dashboard erreichst und die du in Thunderbird einträgst. Trage dort die feste IP-Adresse des LXC-Containers ein (nicht localhost), damit alle Geräte im Netzwerk den Proxy erreichen können.

Konfiguration

Konfiguration

SMTP-Zugänge anlegen

Bevor Thunderbird oder ein anderes Mailprogramm den Proxy nutzen kann, muss mindestens ein SMTP-Zugang angelegt werden. Diese Zugangsdaten sind unabhängig von den Web-UI-Benutzern und dienen ausschließlich zur Authentifizierung am Proxy.

1. Öffne das Web-UI und navigiere zu Konfiguration → SMTP-Zugänge
2. Klicke auf Zugang anlegen
3. Vergib einen Benutzernamen (z.B. den Vornamen oder die E-Mail-Adresse des Mitarbeiters) und ein Passwort
4. Speichern — der Zugang ist sofort aktiv

Du kannst beliebig viele Zugänge anlegen — z.B. einen pro Mitarbeiter oder einen gemeinsamen für das ganze Team.

Thunderbird einrichten

Ändere in Thunderbird den Postausgangsserver auf den Signaturmonster-Proxy. Die Einstellung findest du unter Konten-Einstellungen → Postausgangs-Server (SMTP).

Erste Signatur erstellen

Öffne das Web-UI unter http://localhost:8080 und navigiere zu Signaturen → Neue Signatur.

1. Gib der Signatur einen Namen (z.B. "Standard-Signatur")
2. Füge Blöcke per Drag & Drop aus der linken Palette hinzu:
   • Text-Block — Freitext, Name, Titel, Abteilung
   • Bild-Block — Logo, Profilbild
   • Link-Block — Website, LinkedIn, etc.
   • Social-Block — vorgefertigte Social-Media-Icons
   • Trennlinie — horizontale Linie
   • Banner-Block — GIF-Banner (aus dem Banner-Editor)
3. Konfiguriere jeden Block in der rechten Seitenleiste
4. Nutze die Live-Vorschau, um das Ergebnis zu sehen
5. Klicke auf Speichern

Variablen nutzen

In Text-Blöcken kannst du Variablen verwenden, die beim Senden automatisch aus der Absender-Datenbank befüllt werden. Variablen werden in doppelte geschweifte Klammern gesetzt:

{{vorname}} {{nachname}}
{{titel}} · {{abteilung}}
{{firma}}

Tel: {{telefon}}
Mobil: {{mobil}}
{{webseite}}

Verfügbare Variablen:

Die Werte werden pro Absender in Einstellungen → Absender hinterlegt und beim Senden automatisch eingesetzt.

CI-Profil anlegen

CI-Profile definieren das visuelle Erscheinungsbild einer Marke: Primärfarbe, Schriftart, Logo, Hintergrundfarbe für den Mail-Body. Über den Mail Beautifier wird der eingehende Mail-Body gesäubert (Fremd-Signaturen entfernt) und in dein CI-Template eingebettet.

1. Navigiere zu Corporate Identity → Neues CI-Profil
2. Lade das Firmenlogo hoch (PNG/SVG, max. 2 MB)
3. Wähle Primärfarbe, Akzentfarbe und Hintergrundfarbe
4. Wähle die Schriftart (Google Fonts werden unterstützt)
5. Aktiviere den Mail Beautifier für dieses Profil
6. Speichern — das Profil steht nun in den Signatur-Regeln zur Verfügung

Regeln konfigurieren

Regeln steuern, welche Signatur (und welches CI-Profil) für welchen Absender verwendet wird. Ohne passende Regel wird eine Mail unverändert weitergeleitet.

1. Navigiere zu Regeln → Neue Regel
2. Gib eine Absender-E-Mail-Adresse ein (oder ein Wildcard-Muster, z.B. *@example.com)
3. Wähle die Signatur, die angewendet werden soll
4. Optional: CI-Profil auswählen
5. Optional: Disclaimer aktivieren
6. Priorität festlegen (niedrigere Zahl = höhere Priorität)
7. Speichern und aktivieren

Disclaimer hinzufügen

Disclaimer werden am Ende jeder E-Mail eingefügt. Sie können als HTML (mit Formatierung) und als Plaintext-Variante hinterlegt werden. Signaturmonster fügt automatisch die richtige Variante je nach Mail-Format ein.

1. Navigiere zu Disclaimer → Neuer Disclaimer
2. Gib den HTML-Text ein (Formatierungen wie <b>, <a> sind erlaubt)
3. Gib die Plaintext-Variante ein
4. Weise den Disclaimer einer oder mehreren Regeln zu

<!-- HTML-Disclaimer -->
<p style="font-size:11px;color:#888">
  Diese E-Mail und ihre Anhänge sind vertraulich und ausschließlich
  für den Empfänger bestimmt. Wenn Sie diese E-Mail irrtümlich
  erhalten haben, informieren Sie bitte den Absender.
  <a href="https://example.com/impressum">Impressum</a>
</p>

Banner & Animationen

Banner & Animationen

Banner erstellen

Der integrierte GIF-Generator erzeugt direkt im Browser animierte GIF-Banner, die als Block in einer Signatur eingebettet werden.

1. Navigiere zu Banner → Neuer Banner
2. Gib dem Banner einen Namen und lege die Dimensionen fest (empfohlen: 600×120 px)
3. Füge Szenen hinzu (mindestens eine Szene ist Pflicht)
4. Konfiguriere jede Szene im Szenen-Editor
5. Klicke auf Vorschau generieren, um das GIF zu rendern
6. Speichern — der Banner steht nun im Signatur-Designer als Banner-Block zur Verfügung

Szenen-Editor

Jede Szene ist ein Frame im GIF. Die Szenen werden der Reihe nach abgespielt und können per Drag & Drop umsortiert werden.

Hintergrund-Typen

Text-Animationen

Szenen-Einstellungen

• Dauer: Wie lange die Szene angezeigt wird (in Sekunden, z.B. 2.0)
• Übergangseffekt: Fade, Cut (scharf) oder Slide zwischen Szenen
• Übergangszeit: Dauer des Übergangs in Sekunden
• Texte: Mehrere Textelemente pro Szene, jedes mit eigenem Rich-Text-Editor

Outlook-Kompatibilität

Outlook unterstützt keine animierten GIFs in E-Mails. Signaturmonster löst das automatisch mit MSO Conditional Comments und CID-Inline-Embedding:

<!--[if mso]>
<img src="cid:banner_fallback"
     width="600" height="120"
     alt="Banner">
<![endif]-->

<!--[if !mso]><!-->
<img src="cid:banner_animated"
     width="600" height="120"
     alt="Banner">
<!--<![endif]-->

Beide Bilder — das animierte GIF und das statische PNG-Fallback aus Szene 1 — werden als CID-Inline-Anhänge in die Mail eingebettet. Das bedeutet:

• Keine externen URLs — kein Tracking, keine Firewall-Probleme
• Bilder werden immer angezeigt, auch ohne Internetverbindung
• Kein Bild-Laden beim Öffnen der Mail notwendig

Erweitert

Erweitert

Benutzer & Rechte

Signaturmonster unterstützt mehrere Benutzer mit unterschiedlichen Rollen. Benutzer werden im Web-UI unter Einstellungen → Benutzer verwaltet.

Rollen

SMTP-Benutzer

Jeder Absender (SMTP-Benutzer) hat eine eigene Eintragung unter Einstellungen → Absender. Dort werden die Profildaten (für Variablen) und die SMTP-Zugangsdaten für den echten Mailserver hinterlegt.

Updates

Der Updater-Service prüft regelmäßig die GitHub Container Registry (ghcr.io/choldermann) auf neue Image-Versionen. Werden neue Versionen gefunden, erscheint im Web-UI eine Benachrichtigung.

Manuelles Update

# Neue Images holen
docker compose pull

# Stack mit neuen Images neu starten
docker compose up -d

# Alte (nicht mehr genutzte) Images aufräumen
docker image prune -f

Automatisches Update

Der integrierte Updater-Service kann so konfiguriert werden, dass er Updates automatisch einspielt. Dies wird über eine Umgebungsvariable gesteuert:

# Automatische Updates aktivieren (true/false)
AUTO_UPDATE=true

# Prüfintervall in Minuten (Standard: 60)
UPDATE_INTERVAL=60

Sicherheit & Kryptografie

S/MIME und PGP — Architekturelle Klarstellung

Signaturmonster ist ein SMTP-Proxy, der Mailinhalte modifiziert (Signatur, Branding, Disclaimer). Das ist strukturell unvereinbar mit Ende-zu-Ende-Kryptografie (S/MIME, PGP), deren Kernaussage lautet: „Ich, der Absender, habe genau diesen Inhalt signiert."

Ein Proxy, der Inhalte verändert und anschließend kryptografisch signiert, könnte diese Aussage nicht treffen — er hat den Inhalt ja verändert. Das ist kein Bug, sondern ein grundlegender Widerspruch, den alle inhaltsmodifizierenden Mailsysteme haben — einschließlich kommerzieller Cloud-Anbieter wie Exclaimer oder CodeTwo.

Workaround für E2E-Signierpflicht

Wer persönliche E2E-Signierung benötigt (z. B. Anwaltskanzleien, Behörden mit QES-Pflicht nach eIDAS):

1. Kryptografische Signatur im Mailclient setzen, bevor die Mail an den Proxy gesendet wird
2. Alle Proxy-Funktionen für diese Mail per #sm:off deaktivieren

Der Befehl #sm:off wird auf einer eigenen Zeile in die Mail geschrieben — der Proxy leitet die Mail dann unverändert weiter. Der Befehl selbst wird vor dem Versand entfernt.

Mail-Queue & Zwischenspeicherung

Eingehende Mails werden beim SMTP-Proxy empfangen und zunächst in einer lokalen SQLite-Queue auf deinem Server zwischengespeichert, bevor Verarbeitung und Weiterleitung starten. Die Mails verbleiben dabei vollständig in deiner Infrastruktur — es besteht zu keinem Zeitpunkt eine Verbindung zu externen Diensten für den Mailversand.

Queue-Übersicht im Web-UI

Unter System → Mail-Queue sind alle Einträge mit Status, Absender, Empfänger und Betreff einsehbar:

Mails herunterladen

Einzelne Mails können direkt aus der Queue-Übersicht heruntergeladen werden — nützlich für Debugging, Audit-Zwecke oder die Prüfung fehlgeschlagener Zustellversuche. Fehlgeschlagene Einträge lassen sich außerdem manuell neu einreihen.

Retry-Strategie

Bei Zustellfehlern wiederholt der Proxy automatisch mit exponentiellem Backoff:

Troubleshooting

Hier sind die häufigsten Probleme und ihre Lösungen:

SMTP-Verbindung schlägt fehl

Überprüfe die Logs des SMTP-Proxy-Containers:

docker compose logs smtp-proxy

Häufige Ursachen:

• Port 587 ist auf dem Host bereits belegt — ändere PROXY_PORT in .env
• SMTP_HOST oder SMTP_PORT falsch konfiguriert
• Firewall blockiert den ausgehenden Port

Web-UI nicht erreichbar

# Status aller Container prüfen
docker compose ps

# nginx-Logs anzeigen
docker compose logs nginx

# Backend-Logs anzeigen
docker compose logs backend

• Stelle sicher, dass Port 8080 (oder dein konfigurierter Port) nicht blockiert ist
• Der Frontend-Container braucht beim ersten Start etwas Zeit zum Starten

Signatur wird nicht injiziert

• Prüfe, ob eine Regel für den Absender existiert und aktiv ist
• Stelle sicher, dass die Mail über den Signaturmonster-Proxy gesendet wurde (Port 587)
• Prüfe die Logs: docker compose logs smtp-proxy

GIF-Banner wird in Outlook nicht angezeigt

• Dies ist erwartetes Verhalten — Outlook zeigt das statische PNG-Fallback
• Prüfe, ob Szene 1 korrekt und visuell sinnvoll ist
• Stelle sicher, dass der Banner als CID eingebettet wird (Standard-Verhalten)

Datenbank-Reset

# Vorsicht: löscht alle Daten!
docker compose down
rm -rf ./data
docker compose up -d