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

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 like chat.mycompany.com will 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:

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

1. Installs Docker and git (if needed)
2. Creates directories under /opt/serahrchat/
3. Generates a Master Key (encryption key for your documents)
4. Automatically starts a 7-day free trial
5. 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.com

The 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:

• src and data-instance — Replace chat.mycompany.com with your SerahrChat domain
• data-color — Optional: Match the color to your brand (e.g. #e11d48 for 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).

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.

Ollama

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

# Download recommended model
ollama pull mistral

# Download embedding model
ollama pull nomic-embed-text

LM 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.sh

10. 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:

1. Open WordPress Admin → Plugins → Add New
2. Upload Plugin → Select the ZIP file → Install
3. 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:

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:

16. Forgot Password

On the login page, click "Forgot password?". Two options are available:

1. Via email: A verification code is sent to the registered email address
2. 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).