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/widget.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/widget.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, 100% 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.

Ollama

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

# Empfohlenes Modell herunterladen
ollama pull mistral

# Embedding-Modell herunterladen
ollama pull nomic-embed-text

LM Studio

Alternativ können Sie LM Studio verwenden. Laden Sie die Software herunter, wählen Sie ein Modell aus dem integrierten Katalog und starten Sie den lokalen Server. LM Studio bietet eine grafische Oberfläche und ist besonders für Einsteiger geeignet.

Wählen Sie anschließend im Admin-Panel unter Einstellungen → API-Provider Ollama (Lokal) oder LM Studio aus.

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

Download: Im Admin-Panel unter Einstellungen → System auf "WordPress-Plugin herunterladen" klicken.

Installation:

1. WordPress Admin öffnen → Plugins → Installieren
2. Plugin hochladen → ZIP-Datei auswählen → Installieren
3. Plugin aktivieren

Konfiguration: WordPress Admin → Einstellungen → SerahrChat → Instanz-URL eintragen (z.B. https://chat.meinefirma.de).

Das Plugin fügt das Widget-Script automatisch auf allen Seiten ein. Keine weiteren Code-Änderungen nötig.

Optional: Position (bottom-right / bottom-left) und Farbe sind im Plugin konfigurierbar.

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).