Documentation — SerahrChat
This guide is intended for administrators who want to install SerahrChat on their own server. No technical expertise is required — the installation is largely automated.
1. System Requirements
| Requirement | Minimum | Recommended |
|---|---|---|
| Operating System | Linux (x86_64) | Ubuntu 22.04 / Debian 12 |
| RAM | 2 GB | 4 GB |
| Disk Space | 1 GB free | 10 GB free |
| CPU | 1 vCPU | 2 vCPU |
| Ports | 80, 443 open | |
| Network | Outbound HTTPS access |
Software (installed automatically if needed): Docker >= 20.x, Docker Compose v2, git, curl
Additionally required:
- Your own domain (e.g.
mycompany.com) where you can manage DNS records. A subdomain likechat.mycompany.comwill be pointed to the server. A custom domain is required because HTTPS certificates cannot be issued for IP addresses. - An OpenRouter API key — or a local AI model with Ollama or LM Studio
- Optional: A SerahrChat license key (the installation automatically starts with a 7-day free trial)
2. Server Setup
We recommend Hetzner Cloud: A CX23 is sufficient (2 vCPU, 4 GB RAM, 40 GB SSD, from approx. EUR 4/month). Data center in Germany.
DNS setup: Create an A record at your domain provider pointing your subdomain to the server IP:
| Type | Name | Value | TTL |
|---|---|---|---|
| A | chat | <Server-IP> | 3600 |
If your domain is mycompany.com and your server IP is 49.12.234.56, this creates chat.mycompany.com → 49.12.234.56. The change may take up to 30 minutes to propagate.
Note for website builder users: If your website only runs under a builder-provided address (e.g. mycompany.builder.com), you cannot manage subdomains or DNS records. In this case, you need your own domain (from approx. EUR 1/month, e.g. from IONOS or Namecheap). You can redirect the domain to your existing website and use a subdomain for SerahrChat at the same time. Also note: to embed the chat widget on your website (see section 7), most website builders require a custom code feature (often called "Custom Code", "Code Embed" or "HTML Widget"). This feature is usually only available on higher-tier plans. Contact our support if you need help.
3. Connect to Server (SSH)
Open a terminal (Windows: PowerShell, macOS/Linux: Terminal) and connect to your server:
With password (if you did not set up an SSH key during server creation):
ssh root@<Server-IP>You will be prompted for the root password. You received this via email from your hosting provider (e.g. Hetzner).
With SSH key (recommended — if you set up a key during server creation):
ssh -i ~/.ssh/id_serahr root@<Server-IP>Replace id_serahr with the name of your SSH key and <Server-IP> with your server's IP address, e.g. ssh -i ~/.ssh/id_rsa root@49.12.234.56
On first connection, confirm the security prompt with yes.
4. Installation
Once connected, run the following command:
curl -fsSL https://update.serahr.de/serahrchat/preflight.sh | sudo bash -s -- --install- Installs Docker and git (if needed)
- Creates directories under
/opt/serahrchat/ - Generates a Master Key (encryption key for your documents)
- Automatically starts a 7-day free trial
- Builds and starts the Docker containers
At the end you will receive the admin panel URL.
5. Enable HTTPS
HTTPS is required for production use. The setup uses free Let's Encrypt certificates — no additional costs. Certificates are renewed automatically.
Prerequisite: Your domain must already point to the server via DNS (A record). If you just created the DNS entry, wait up to 30 minutes.
The script requires two parameters:
- Domain — The domain where SerahrChat should be accessible (without
https://) - Email — Your email address for certificate notifications from Let's Encrypt
sudo bash /opt/serahrchat/scripts/setup-tls.sh <your-domain> <your-email>Example:
sudo bash /opt/serahrchat/scripts/setup-tls.sh chat.mycompany.com admin@mycompany.comThe script requests a TLS certificate, configures nginx for HTTPS, and sets up automatic certificate renewal. HTTP is automatically redirected to HTTPS.
6. Setup Wizard
Open https://chat.mycompany.com/admin/ui/ in your browser. The setup wizard guides you through:
- Create account — Enter username, password and email address. You will receive a one-time password via email for verification
- Choose AI provider — OpenRouter (recommended), OpenAI, Mistral, or local (Ollama / LM Studio)
- Enter API key — Your key from the chosen provider
- Choose AI model — Fast & cheap, balanced, or highest quality
- Upload documents — PDFs, Word files, or text documents
- Test — Ask a question to verify answer quality
7. Embed Widget
The chat widget is embedded on your existing company website. Replace chat.mycompany.com in the code below with the domain you set up for your SerahrChat instance in step 5.
Example: If your company website is www.mycompany.com and SerahrChat runs on chat.mycompany.com, the code looks like this:
HTML / static websites — add this code before </body>:
<script
src="https://chat.mycompany.com/embed/widget.js"
data-instance="https://chat.mycompany.com"
data-position="bottom-right"
data-color="#2563eb"
></script>You only need to change two things:
srcanddata-instance— Replacechat.mycompany.comwith your SerahrChat domaindata-color— Optional: Match the color to your brand (e.g.#e11d48for red)
Next.js / React — in your layout.tsx:
import Script from 'next/script'
<Script
src="https://chat.mycompany.com/embed/widget.js"
data-instance="https://chat.mycompany.com"
data-position="bottom-right"
data-color="#2563eb"
strategy="lazyOnload"
/>WordPress: Install the SerahrChat plugin via Plugins → Add New → Upload Plugin, then enter your instance URL under Settings → SerahrChat. The code is then added automatically.
Website builders: Paste the HTML code shown above using your provider's custom code feature (see the note in section 2 for requirements and plan tiers).
| Parameter | Description | Default |
|---|---|---|
data-instance | URL of your SerahrChat instance | required |
data-position | bottom-right or bottom-left | bottom-right |
data-color | Button color (hex code) | #2563eb |
CORS: If the widget is embedded on a different domain (e.g. instance on chat.mycompany.com, widget on www.mycompany.com), add the widget domain as an allowed origin in the admin panel under Settings.
8. Local AI Model with Ollama or LM Studio (optional)
Important note on hardware requirements: Local AI models require a dedicated graphics card (GPU) with its own graphics memory (VRAM). Standard cloud servers do not have a GPU.
| GPU Memory (VRAM) | Suitable Models | Answer Quality |
|---|---|---|
| 4 GB | Gemma 2B, Phi-3 Mini | Simple FAQs |
| 8 GB | Mistral 7B, Llama 3.1 8B | Good quality |
| 16 GB+ | Mistral Small, Llama 3.1 70B | Very good quality |
Ollama
# Install Ollama
curl -fsSL https://ollama.com/install.sh | sh
# Download recommended model
ollama pull mistral
# Download embedding model
ollama pull nomic-embed-textLM Studio
Alternatively, use LM Studio. Download the software, choose a model from the built-in catalog, and start the local server.
9. Backup and Restore
A daily automatic backup is configured during installation. The last 3 backups are retained.
bash /opt/serahrchat/scripts/restore.sh10. Updates
Security updates are installed automatically. Feature updates are shown in the admin panel and installed with a single click. Failed updates automatically roll back.
11. GDPR Template
If you use SerahrChat on your website, include the following template in your privacy policy:
AI-Powered FAQ Assistant
Our website uses an AI-powered FAQ assistant (SerahrChat) that answers questions based on our uploaded documents.
Data processing: Your inputs are processed directly on our own server. Data only leaves our server for the query to the AI language service.
Stored data: Chat histories are stored anonymously and automatically deleted after 90 days.
Legal basis: Art. 6(1)(f) GDPR (legitimate interest).
This template is a suggested wording and does not constitute legal advice.
12. Managing Documents
Supported formats: PDF, Word (.docx), text files (.txt, .md), CSV
Maximum file size: 50 MB per document
Upload documents: In the admin panel under Documents, click "Upload" and select your files. After upload, documents are automatically processed (text extraction, chunking, embedding).
The status changes from "Processing" to "Ready" — or to "Error" if problems occur.
To delete a document, click the trash icon next to it. A confirmation prompt will appear.
Tips:
- Shorter, well-structured documents produce better answers than a single large PDF
- FAQ lists in the format "Question: ... Answer: ..." work particularly well
- The document limit depends on your plan: Basis: 10 documents, Professional: unlimited
13. WordPress Plugin
Download: In the admin panel under Settings → System, click "Download WordPress Plugin".
Installation:
- Open WordPress Admin → Plugins → Add New
- Upload Plugin → Select the ZIP file → Install
- Activate the plugin
Configuration: WordPress Admin → Settings → SerahrChat → Enter your instance URL (e.g. https://chat.mycompany.com).
The plugin automatically adds the widget script to all pages. No further code changes needed.
Optional: Position (bottom-right / bottom-left) and color can be configured in the plugin settings.
14. Budget & Costs
SerahrChat uses external AI services (e.g. OpenRouter) for answer generation. Costs depend on the chosen model:
| Model Type | Cost per Question (approx.) | Suitable for |
|---|---|---|
| Fast models | ~$0.001 | Simple FAQs, high volume |
| High-quality models | ~$0.01 | Complex questions, highest quality |
In the admin panel under Settings → Budget, you can set a monthly limit.
Thresholds:
- 80% reached: Warning in the dashboard
- 95% reached: Only text excerpts from documents (no AI-generated answer)
- When the limit is reached: Chat pauses until the next month
The budget resets automatically on the 1st of each month. Default budget: $10/month (sufficient for approx. 1,000–10,000 questions depending on the model).
Tip: Start with a cheaper model and switch to a higher-quality one if needed.
15. Settings Overview
All settings can be found in the admin panel under Settings:
| Setting | Description |
|---|---|
| Chatbot Name | Name shown in the widget header (default: "FAQ Assistant") |
| Welcome Message | Greeting text when the chat window opens (configurable in DE + EN) |
| No Match Response | What the bot says when no relevant documents are found |
| Widget Color | Customizable to match your brand (hex color code) |
| Widget Position | Bottom right or bottom left |
| Bubble Label + Icon | Customizable text and icon on the chat button (Pro feature) |
| Allowed Domains (CORS) | Domains where the widget may be embedded |
| Conversation Memory | How many previous messages the bot uses as context (default: 10) |
| Custom Instructions | Custom rules for the bot (e.g. "Always respond in German", "Refer pricing questions to the contact page") |
16. Forgot Password
On the login page, click "Forgot password?". Two options are available:
- Via email: A verification code is sent to the registered email address
- Via recovery code: Enter one of the 5 recovery codes that were generated during your first login
Tip: Keep your recovery codes in a safe place (e.g. a password manager) — they are your last resort if the email address is unreachable.
If neither option works: Connect to the server via SSH and reset the password directly (see server documentation).
17. Troubleshooting
Site not reachable: Wait 1–2 minutes after an update. Check /health.
Widget not responding: Check data-instance (no trailing /). Check CORS settings.
Chat returns error: Check your API balance and monthly budget in the admin panel.
18. Support
Support response times: Basis plan: 72 hours — Pro/Lifetime plan: 24 hours (business days Mon–Fri).