Simmetric Chat
Zurück zur Dokumentation
Guide 01

Erste Schritte

Simmetric Chat ist eine lokale, air-gap-fähige KI-Chat-Plattform: sie funktioniert ohne Verbindung zu externen Cloud-Diensten, mit lokalem LLM (Ollama), lokalen Embeddings (Xenova) und lokaler Vektor-DB (LanceDB). Sie kann jedoch Cloud-Anbieter (OpenAI, …

3 Min. Lesezeit

Simmetric Chat ist eine lokale, air-gap-fähige KI-Chat-Plattform: sie funktioniert ohne Verbindung zu externen Cloud-Diensten, mit lokalem LLM (Ollama), lokalen Embeddings (Xenova) und lokaler Vektor-DB (LanceDB). Sie kann jedoch Cloud-Anbieter (OpenAI, Anthropic, OpenRouter) und eine entfernte Vektor-DB (Qdrant) nutzen, wenn diese konfiguriert sind.

Voraussetzungen

  • Node.js ≥ 24 und pnpm 11.24.0 (der Monorepo-Manager; `corepack enable && corepack prepare [email protected] --activate`)
  • PostgreSQL 16 (Hauptdatenbank)
  • Ollama (optional, aber empfohlen für das lokale LLM) - https://ollama.com
  • Docker + Docker Compose (für die containerisierte Bereitstellung, siehe 09 - Deployment)

Prüfen:

bash
node -v && pnpm -v && psql --version

Installation (lokale Entwicklung)

bash
git clone <repo> simmetric-chat
cd simmetric-chat
pnpm install

Das Monorepo nutzt pnpm workspaces + Turborepo. Die Pakete liegen in packages/: shared, server, frontend, collector, widget, plus die Desktop-App src-tauri/.

Umgebungsvariablen

Alle Pakete lesen die `.env` im Repo-Root (die einzige Laufzeitkonfigurationsdatei; die alte pro-Paket-.env-Ebene wurde entfernt: Vorrang process.env > Root-.env > Code-Standard). Erstellen Sie die minimale Datei:

bash
cp .env.example .env

Erforderliche Secrets (JWT_SECRET, COLLECTOR_SECRET) und der Widget-Schlüssel:

env
JWT_SECRET=$(openssl rand -hex 32)
COLLECTOR_SECRET=$(openssl rand -hex 32)
WIDGET_API_KEY=$(openssl rand -hex 32)
DATABASE_URL=postgresql://simmetricchat:simmetricchat@localhost:5432/simmetricchat
LLM_PROVIDER=ollama
LLM_MODEL=gemma4:latest
OLLAMA_BASE_URL=http://localhost:11434

WIDGET_API_KEY wird vom Widget-Dienst benötigt (dessen eigenes Zod-Schema beendet den Prozess ohne sie); der Server registriert sie beim Start als API-Key des Kontos widget-service (idempotent). Optional in der Entwicklung: API_KEY_HMAC_SECRET (die sk--API-Keys bleiben unbrauchbar, bis sie gesetzt ist) und ENCRYPTION_KEY (Fallback scryptSync(JWT_SECRET); in Produktion erforderlich). Ein fehlender LICENSE_KEY bedeutet den Community-Build.

Vollständige Umgebungsvariablen-Tabelle: 03 - Configuration.

Datenbank

Erstellen Sie die PostgreSQL-Datenbank (z.B. docker compose -f docker/docker-compose.infra.yml up -d postgres), generieren Sie dann den Prisma-Client, wenden Sie die Migrationen und den Seed an:

bash
pnpm db:generate                  # generiert den Prisma-Client (+ Prisma-7/pnpm-Symlink-Fix)
pnpm --filter server db:migrate   # wendet die Migrationen an (interaktiv)
pnpm --filter server db:seed      # Standardrollen (Admin, Superuser, User), Berechtigungen, Config, Templates

Alternative zum manuellen Seed: bei leerer Datenbank zeigt das Frontend den Setup- Assistenten in 4 Schritten (Admin, LLM-Anbieter, Vektor-DB) - oder der Server seedet den Bootstrap-Admin automatisch (SEED_BOOTSTRAP_ADMIN=true standardmäßig, konfigurierbar via SEED_ADMIN_USERNAME / SEED_ADMIN_PASSWORD / SEED_ADMIN_EMAIL, Standard admin / admin123 / [email protected] mit mustChangePassword=true). Die Selbstregistrierung ist standardmäßig geschlossen (ALLOW_REGISTRATION=false): ein Admin erstellt Benutzer über Settings oder via POST /api/auth/admin-register.

Entwicklung starten

Ein einziger Befehl startet alle Dienste über Turborepo:

bash
pnpm dev

Standard-Ports:

ServicePortBeschreibung
frontend5173Vite-SPA (React 19), Proxy /api → server
server3000Express-API + Swagger unter /api-docs
collector3210Microservice für Dokumenterfassung
widget3211Einbettbarer Widget-Dienst (Preact)

Öffnen Sie http://localhost:5173, melden Sie sich mit admin / admin123 an und ändern Sie das Passwort.

Wenn Ollama nicht läuft, schlagen Chats mit einem Verbindungsfehler fehl. Laden Sie ein
Modell mit ollama pull gemma4:latest && ollama serve herunter oder konfigurieren Sie
einen Cloud-Anbieter unter Settings → Providers.

Kurze UI-Tour

  • Sidebar - nach Rolle gefilterte Gruppen: Overview (Dashboard), Chat (Chat, Projects, Workspaces), Knowledge (Documents, Wissensbasis, Uploads), Platform (Widgets, Marketplace, Analytics - Admin), System (Eventlog, SSO - Admin/Enterprise). Die Einträge folgen den 13 RBAC-Menüabschnitten.
  • Chat - Token-für-Token-Streaming, Modellauswahl pro Chat (Cmd+K-Palette), Side-by-Side-Vergleich (Cmd+Shift+M), RAG-Zitate, /model-Slash-Befehl.
  • Documents - Drag-&-Drop-Upload (PDF, DOCX, XLSX, PPTX, TXT, MD, CSV, Bilder mit OCR), Status pending → processing → completed → failed.
  • Settings - 5 Haupt-Tabs (Profil, LLM-Anbieter, Erscheinungsbild, Sicherheit, Erweitert), die die Unterabschnitte verschachteln: Providers, LLM & Embedding, Vector DB, API Keys, Roles, Users, MCP Connections, Maintenance, Backups, DLP, Widget (eigene Seite), OCR, usw.
  • Maintenance - One-Click-RAG-Reindex nach einem Wechsel des Embedding-Modells.

Empfohlene erste Schritte

  1. Konfigurieren Sie einen Anbieter - Settings → Providers: Ollama (lokal) oder OpenAI/Anthropic hinzufügen.
  2. Erstellen Sie einen Workspace und ein Projekt - Dokumente und Chats sind workspace-gebunden.
  3. Laden Sie ein Dokument hoch - Documents → Upload; warten Sie auf den Status completed.
  4. Chatten Sie - öffnen Sie einen Chat im Workspace und stellen Sie Fragen zum Dokument (hybrides RAG).
  5. (Admin) Entdecken Sie den Marketplace - installieren Sie einen MCP-Server, um den Agenten um Tools zu erweitern.

Nächste Schritte