Dokumentation — SerahrChat

Diese Anleitung richtet sich an Administratoren, die SerahrChat auf einem eigenen Server installieren möchten. Technische Vorkenntnisse sind nicht erforderlich — die Installation ist weitgehend automatisiert.

1. Systemvoraussetzungen

Software (wird bei Bedarf automatisch installiert): Docker >= 20.x, Docker Compose v2, git, curl

Zusätzlich benötigt:

• Eine eigene Domain (z.B. meinefirma.de), bei der Sie DNS-Einträge verwalten können. Davon wird eine Subdomain wie chat.meinefirma.de auf den Server eingerichtet. Eine eigene Domain ist notwendig, weil HTTPS-Zertifikate nicht für IP-Adressen ausgestellt werden können.
• Einen OpenRouter API-Key — oder ein lokales KI-Modell mit Ollama oder LM Studio
• Optional: Einen SerahrChat-Lizenzschlüssel (die Installation startet automatisch mit einer 7-Tage-Testversion)

2. Server vorbereiten

Wir empfehlen Hetzner Cloud als Hosting-Anbieter: Ein CX23 genügt (2 vCPU, 4 GB RAM, 40 GB SSD, ab ca. 4 EUR/Monat). Rechenzentrum in Deutschland.

Jeder Linux-Server mit den oben genannten Mindestvoraussetzungen ist geeignet. Stellen Sie sicher, dass Ports 80 und 443 in der Firewall geöffnet sind und SSH-Zugang besteht.

DNS einrichten: Erstellen Sie bei Ihrem Domain-Provider einen A-Record, der Ihre Subdomain auf die Server-IP zeigt:

Wenn Ihre Domain meinefirma.de ist und der Server die IP 49.12.234.56 hat, wird daraus chat.meinefirma.de → 49.12.234.56. Die Änderung kann bis zu 30 Minuten dauern.

Hinweis für Nutzer von Website-Baukästen: Wenn Ihre Website nur unter einer Adresse des Baukasten-Anbieters läuft (z.B. meinefirma.anbieter.com), können Sie keine Subdomains und keine DNS-Einträge verwalten. In diesem Fall benötigen Sie eine eigene Domain (ab ca. 1 EUR/Monat, z.B. bei IONOS oder Namecheap). Die Domain können Sie auf Ihre bestehende Website weiterleiten und gleichzeitig eine Subdomain für SerahrChat nutzen. Beachten Sie außerdem: Um das Chat-Widget auf Ihrer Website einzubinden (siehe Abschnitt 7), benötigen die meisten Baukasten-Anbieter eine Funktion zum Einfügen von eigenem Code (oft "Custom Code", "Code-Einbettung" oder "HTML-Widget" genannt). Diese Funktion ist in der Regel erst ab einem höheren Tarif verfügbar. Bei Fragen hilft Ihnen unser Support gerne weiter.

3. Mit dem Server verbinden (SSH)

Öffnen Sie ein Terminal (Windows: PowerShell, macOS/Linux: Terminal) und verbinden Sie sich mit Ihrem Server:

Mit Passwort (falls Sie bei der Servererstellung keinen SSH-Key hinterlegt haben):

ssh root@<Server-IP>

Sie werden nach dem Root-Passwort gefragt. Dieses haben Sie per E-Mail von Ihrem Hosting-Anbieter erhalten (z.B. Hetzner).

Mit SSH-Key (empfohlen — falls Sie bei der Servererstellung einen Key hinterlegt haben):

ssh -i ~/.ssh/id_serahr root@<Server-IP>

Ersetzen Sie id_serahr durch den Namen Ihres SSH-Keys und <Server-IP> durch die IP-Adresse Ihres Servers, z.B. ssh -i ~/.ssh/id_rsa root@49.12.234.56

Beim ersten Verbinden erscheint eine Sicherheitsabfrage — mit yes bestätigen.

4. Installation

Auf dem Server angekommen, führen Sie folgenden Befehl aus:

curl -fsSL https://update.serahr.de/serahrchat/preflight.sh | sudo bash -s -- --install

Das Script prüft automatisch alle Voraussetzungen (Docker, RAM, Ports, etc.) und führt die Installation durch:

1. Installiert Docker und git (falls nötig)
2. Erstellt Verzeichnisse unter /opt/serahrchat/
3. Generiert einen Master Key (Verschlüsselungsschlüssel für Ihre Dokumente)
4. Startet automatisch eine 7-Tage-Testversion
5. Baut und startet die Docker-Container

Am Ende erhalten Sie die URL zum Admin-Panel.

5. HTTPS aktivieren

HTTPS ist für den Produktivbetrieb erforderlich. Das Setup nutzt kostenlose Let's Encrypt Zertifikate — es fallen keine zusätzlichen Kosten an. Die Zertifikate werden automatisch erneuert.

Voraussetzung: Ihre Domain muss per DNS bereits auf den Server zeigen (A-Record). Falls Sie den DNS-Eintrag gerade erst erstellt haben, warten Sie bis zu 30 Minuten.

Das Script erwartet zwei Angaben:

• Domain — Die Domain unter der SerahrChat erreichbar sein soll (ohne https://)
• E-Mail — Ihre E-Mail-Adresse für Zertifikats-Benachrichtigungen von Let's Encrypt

sudo bash /opt/serahrchat/scripts/setup-tls.sh <Ihre-Domain> <Ihre-E-Mail>

Beispiel:

sudo bash /opt/serahrchat/scripts/setup-tls.sh chat.meinefirma.de admin@meinefirma.de

Das Script beantragt ein TLS-Zertifikat, konfiguriert nginx für HTTPS und richtet automatische Zertifikatserneuerung ein. HTTP wird automatisch auf HTTPS umgeleitet.

6. Setup-Wizard

Öffnen Sie https://chat.meinefirma.de/admin/ui/ im Browser. Der Setup-Wizard führt Sie durch:

• Konto erstellen — Benutzername, Passwort und E-Mail-Adresse angeben. Sie erhalten ein Einmalpasswort per E-Mail zur Bestätigung
• KI-Anbieter wählen — OpenRouter (empfohlen), OpenAI, Mistral oder lokal (Ollama / LM Studio)
• API-Key eingeben — Ihren Schlüssel vom gewählten Anbieter
• KI-Modell wählen — Schnell & günstig, ausgewogen oder höchste Qualität
• Dokumente hochladen — PDFs, Word-Dateien oder Textdokumente
• Test — Stellen Sie eine Frage, um die Antwortqualität zu prüfen

7. Widget einbetten

Das Chat-Widget wird auf Ihrer bestehenden Firmenwebsite eingebunden. Ersetzen Sie im folgenden Code chat.meinefirma.de durch die Domain, die Sie in Schritt 5 für Ihre SerahrChat-Instanz eingerichtet haben.

Beispiel: Wenn Ihre Firmenwebsite www.meinefirma.de ist und SerahrChat unter chat.meinefirma.de läuft, dann sieht der Code so aus:

HTML / statische Websites — fügen Sie diesen Code vor </body> ein:

<script
  src="https://chat.meinefirma.de/embed/embed.min.js"
  data-instance="https://chat.meinefirma.de"
  data-position="bottom-right"
  data-color="#2563eb"
></script>

Dabei müssen Sie nur zwei Stellen anpassen:

• src und data-instance — Ersetzen Sie chat.meinefirma.de durch Ihre SerahrChat-Domain
• data-color — Optional: Passen Sie die Farbe an Ihr Firmendesign an (z.B. #e11d48 für Rot)

Next.js / React — in Ihrer layout.tsx:

import Script from 'next/script'

<Script
  src="https://chat.meinefirma.de/embed/embed.min.js"
  data-instance="https://chat.meinefirma.de"
  data-position="bottom-right"
  data-color="#2563eb"
  strategy="lazyOnload"
/>

WordPress: Installieren Sie das SerahrChat-Plugin unter Plugins → Installieren → Plugin hochladen, und tragen Sie die URL Ihrer Instanz unter Einstellungen → SerahrChat ein. Der Code wird dann automatisch eingefügt.

Website-Baukästen: Fügen Sie den oben gezeigten HTML-Code über die Custom-Code-Funktion Ihres Anbieters ein (siehe Hinweis in Abschnitt 2 zu Voraussetzungen und Tarifen).

CORS: Falls das Widget auf einer anderen Domain eingebettet wird (z.B. Instanz auf chat.meinefirma.de, Widget auf www.meinefirma.de), tragen Sie die Widget-Domain im Admin-Bereich unter Einstellungen als erlaubte Herkunft ein.

8. Lokales KI-Modell mit Ollama oder LM Studio (optional)

Anstatt einen Cloud-Dienst zu nutzen, können Sie ein KI-Modell direkt auf Ihrem Server betreiben — keine API-Kosten, volle Datensouveränität, keine Abhängigkeit von externen Diensten.

Wichtiger Hinweis zu den Hardware-Anforderungen: Lokale KI-Modelle benötigen eine dedizierte Grafikkarte (GPU) mit eigenem Grafikspeicher (VRAM). VRAM ist nicht dasselbe wie der normale Arbeitsspeicher (RAM) Ihres Servers. Herkömmliche Cloud-Server (z.B. Hetzner CX- oder CPX-Reihe) verfügen nicht über eine GPU und sind für lokale KI-Modelle nicht geeignet.

Hardware-Empfehlungen

Getestet: NVIDIA RTX 2080 Super (8 GB VRAM) mit Qwen3-8B + BGE-M3 gleichzeitig geladen (~6,3 GB VRAM). Liefert korrekte, quellenbasierte Antworten ohne Halluzinationen.

Ollama

# Ollama installieren
curl -fsSL https://ollama.com/install.sh | sh

# Empfohlenes LLM herunterladen
ollama pull qwen3:8b

# Empfohlenes Embedding-Modell (multilingual, ideal für deutsche Dokumente)
ollama pull bge-m3

LM Studio

Alternativ können Sie LM Studio verwenden — besonders geeignet für Windows und macOS:

1. LM Studio herunterladen und installieren
2. Im Discover-Tab nach Qwen3-8B-GGUF suchen, Q4_K_M wählen
3. Nach bge-m3-GGUF suchen und herunterladen
4. Beide Modelle laden und den Server starten (Developer-Tab)

Wichtig für 8 GB VRAM: Context Length auf 4096–8192 einstellen (nicht höher), strukturierte Ausgabe deaktivieren, nur LLM + Embedding gleichzeitig laden.

Wählen Sie anschließend im Admin-Panel unter Einstellungen → API-Provider Ollama / Eigener Server oder LM Studio / Eigener Server aus.

Empfohlene Modelle

LLM (Antwortgenerierung)

Embedding (Dokumenten-Suche)

Hinweis: BGE-M3 liefert bei deutschsprachigen Dokumenten deutlich bessere Suchergebnisse als nomic-embed-text. Nach einem Wechsel des Embedding-Modells werden alle Dokumente automatisch neu eingebettet.

9. Backup und Wiederherstellung

Bei der Installation wird ein tägliches automatisches Backup eingerichtet. Es sichert die Datenbank, den Suchindex und alle Dokumente. Die letzten 3 Backups werden aufbewahrt.

# Backup wiederherstellen
bash /opt/serahrchat/scripts/restore.sh

10. Updates

Sicherheitsupdates werden automatisch im Hintergrund installiert. Feature-Updates und Bugfixes werden im Admin-Panel unter System angezeigt und per Klick installiert.

Falls ein Update fehlschlägt, wird automatisch auf die letzte funktionierende Version zurückgerollt. Sie müssen nichts tun — kein SSH-Zugang erforderlich.

11. DSGVO-Textbaustein

Wenn Sie SerahrChat auf Ihrer Website einsetzen, nehmen Sie folgenden Textbaustein in Ihre Datenschutzerklärung auf (markierte Stellen anpassen):

KI-gestützter FAQ-Assistent

Auf unserer Website setzen wir einen KI-gestützten FAQ-Assistenten (SerahrChat) ein. Der Assistent beantwortet Ihre Fragen auf Basis unserer hinterlegten Dokumente.

Datenverarbeitung: Ihre Eingaben werden direkt auf unserem eigenen Server verarbeitet. Die Daten verlassen unseren Server nur für die Anfrage an den KI-Sprachdienst (OpenRouter / [ANBIETER EINTRAGEN]).

Gespeicherte Daten: Chat-Verläufe werden anonymisiert gespeichert und nach 90 Tagen automatisch gelöscht. IP-Adressen werden anonymisiert (letztes Oktett = 0).

Rechtsgrundlage: Art. 6 Abs. 1 lit. f DSGVO (berechtigtes Interesse).

Dieser Textbaustein ist ein Formulierungsvorschlag und ersetzt keine Rechtsberatung.

12. Dokumente verwalten

Unterstützte Formate: PDF, Word (.docx), Textdateien (.txt, .md), CSV

Maximale Dateigröße: 50 MB pro Dokument

Dokumente hochladen: Im Admin-Panel unter Dokumente auf "Hochladen" klicken und Dateien auswählen. Nach dem Upload werden Dokumente automatisch verarbeitet (Textextraktion, Chunking, Embedding).

Der Status wechselt von "Verarbeitung" zu "Bereit" — oder zu "Fehler", falls Probleme auftreten.

Zum Löschen klicken Sie auf das Papierkorb-Icon neben dem Dokument. Eine Bestätigung wird abgefragt.

Tipps:

• Kürzere, gut strukturierte Dokumente liefern bessere Antworten als ein einzelnes großes PDF
• FAQ-Listen im Format "Frage: ... Antwort: ..." funktionieren besonders gut
• Das Dokumenten-Limit hängt vom Plan ab: Basis: 10 Dokumente, Professional: unbegrenzt

13. WordPress-Plugin

Wenn Ihre Website auf WordPress läuft, installieren Sie das SerahrChat-Plugin — dann müssen Sie keinen HTML-Code anfassen.

Schritt 1: Plugin herunterladen

Loggen Sie sich in Ihrer SerahrChat-Instanz als Admin ein (https://chat.ihre-domain.de/admin/ui/). Gehen Sie zu Einstellungen → System und klicken Sie auf "WordPress-Plugin herunterladen". Sie erhalten eine .zip-Datei.

Schritt 2: Plugin in WordPress hochladen

1. Im WordPress-Admin zu Plugins → Installieren gehen
2. Oben auf "Plugin hochladen" klicken
3. Die eben heruntergeladene ZIP-Datei auswählen und "Jetzt installieren" klicken
4. Nach erfolgreicher Installation auf "Plugin aktivieren" klicken

Schritt 3: Chat-Server-URL eintragen (Pflicht)

Nach der Aktivierung erscheint oben in WordPress ein gelber Hinweis „Jetzt einrichten“. Klicken Sie darauf — oder gehen Sie direkt zu Einstellungen → SerahrChat.

Dort gibt es nur eine wirklich wichtige Einstellung: die Chat-Server-URL. Das ist die Internet-Adresse, unter der Ihre SerahrChat-Installation läuft — dieselbe Adresse, die Sie in Schritt 5 für Ihre Instanz eingerichtet haben.

Beispiel: https://chat.ihre-domain.de

• Die URL muss mit https:// beginnen
• Kein Schrägstrich am Ende
• Kein Pfad dahinter (nicht /admin, nicht /api)

Auf „Änderungen speichern“ klicken — fertig. Das Plugin fügt das Chat-Widget jetzt automatisch auf allen Seiten Ihrer Website ein.

Optional: Position und Farbe

Auf derselben Einstellungsseite können Sie wählen, ob die Chat-Bubble unten rechts oder unten links erscheinen soll. Die Farbe können Sie an Ihr Corporate Design anpassen.

Das Widget erscheint nicht — was tun?

1. Browser-Cache leeren: Strg+Shift+R (oder Cmd+Shift+R am Mac) auf Ihrer Website
2. WordPress-Cache leeren: Falls Sie ein Caching-Plugin (LiteSpeed Cache, W3 Total Cache, WP Rocket, WP Super Cache) nutzen, leeren Sie dort den Cache
3. Quelltext prüfen: Öffnen Sie Ihre Website und drücken Sie Strg+U. Suchen Sie im Quelltext nach SerahrChat. Sie finden dort einen Hinweis-Kommentar — der zeigt Ihnen, ob das Plugin aktiv ist und was ggf. fehlt.
4. CORS-Origin hinterlegen: Falls Ihre WordPress-Domain anders ist als Ihre Chat-Server-Domain (z.B. Chat auf chat.ihre-domain.de, Website auf www.ihre-domain.de), müssen Sie die WordPress-Domain im Admin-Panel unter Einstellungen → CORS-Origins eintragen — sonst blockiert der Browser die Chat-API-Aufrufe.

14. Budget & Kosten

SerahrChat nutzt externe KI-Dienste (z.B. OpenRouter) für die Antwortgenerierung. Die Kosten hängen vom gewählten Modell ab:

Im Admin-Panel unter Einstellungen → Budget können Sie ein monatliches Limit festlegen.

Schwellenwerte:

• 80% erreicht: Warnung im Dashboard
• 95% erreicht: Nur noch Textauszüge aus Dokumenten (keine KI-Antwort)
• Bei Erreichen des Limits: Chat pausiert bis zum nächsten Monat

Das Budget wird am 1. jedes Monats automatisch zurückgesetzt. Standard-Budget: $10/Monat (reicht für ca. 1.000–10.000 Fragen je nach Modell).

Tipp: Starten Sie mit einem günstigen Modell und wechseln Sie bei Bedarf auf ein hochwertigeres.

15. Einstellungen im Überblick

Alle Einstellungen finden Sie im Admin-Panel unter Einstellungen:

16. Passwort vergessen

Auf der Login-Seite auf "Passwort vergessen?" klicken. Es stehen zwei Optionen zur Verfügung:

1. Per E-Mail: Ein Verifizierungscode wird an die hinterlegte E-Mail-Adresse gesendet
2. Per Recovery-Code: Einen der 5 Recovery-Codes eingeben, die beim ersten Login erstellt wurden

Tipp: Recovery-Codes sicher aufbewahren (z.B. im Passwort-Manager) — sie sind der letzte Weg ins System, wenn die E-Mail nicht erreichbar ist.

Falls beides nicht funktioniert: Per SSH auf den Server verbinden und das Passwort direkt zurücksetzen (siehe Server-Dokumentation).

17. Fehlerbehebung

Seite nicht erreichbar: Warten Sie 1–2 Minuten nach einem Update. Prüfen Sie /health — sollte "ok" anzeigen.

Widget antwortet nicht: Prüfen Sie data-instance im Widget-Code (kein abschließendes /). Prüfen Sie CORS im Admin-Bereich.

Chat antwortet mit Fehler: Prüfen Sie Ihr API-Guthaben beim LLM-Anbieter und das monatliche Budget im Admin-Bereich.

18. Support

Support-Reaktionszeiten: Basis-Plan: 72 Stunden — Pro-/Lifetime-Plan: 24 Stunden (Werktage Mo–Fr).