Installation (Entwicklung)

Diese Anleitung bringt Orimora für Entwicklung und Evaluation auf deinem Rechner zum Laufen. Für den empfohlenen Weg brauchst du keine Docker-Vorkenntnisse.

Für Produktion auf deinem eigenen Server siehe Deployment. Für Coolify siehe Coolify Setup.

Welcher Weg passt?

Weg	Für wen	Was du installierst
A — Docker Compose (empfohlen)	Einsteiger, schneller Start	Nur Docker Desktop — Postgres, Redis und Mailpit starten automatisch
B — Native Yarn	Aktive Entwicklung am Code	Node.js 22+, Yarn, PostgreSQL 16+, Redis 7+ auf deinem Rechner

Beide Wege nutzen dieselbe .env-Datei. Die Variablen-Referenz unten gilt für beide.

---

Weg A — Docker Compose (empfohlen)

1. Docker Desktop installieren (Mac/Windows) oder Docker Engine + Compose unter Linux. Prüfen:

   docker compose version

2. Repository klonen und Node-Abhängigkeiten installieren:

   git clone https://github.com/defcon1702/orimora.git orimora
   cd orimora
   yarn install

3. Infrastruktur starten (PostgreSQL, Redis, Mailpit):

   docker compose up -d

   Liest docker-compose.yml im Repo-Root. Dienste:

   Dienst	Zweck	Host-Port
   postgres	Datenbank	5433 → Container 5432
   redis	Sessions, Queues, Rate Limits	6379
   mailpit	Fängt ausgehende E-Mails ab (Magic Links)	SMTP 1026, Web-UI 9025

   Optionale Redis-GUI (Profil tools): docker compose --profile tools up -d → http://localhost:8081

4. .env-Datei anlegen:

   cp .env.example .env

   Füge diese minimale, funktionierende Dev-Konfiguration ein (die Geheimnisse sind Beispiele — erzeuge für alles Geteilte eigene Werte):

   # ── Required ─────────────────────────────────────────────
   DATABASE_URL=postgresql://kb:kb_dev_password@localhost:5433/knowledgebase
   REDIS_URL=redis://localhost:6379
   APP_URL=http://localhost:5173
   SESSION_SECRET=PASTE_64_HEX_CHARS_HERE
   MAGIC_LINK_SECRET=PASTE_ANOTHER_64_HEX_CHARS_HERE
   LLM_ENCRYPTION_KEY=PASTE_THIRD_64_HEX_CHARS_HERE
   PUBLISHING_ENCRYPTION_KEY=PASTE_FOURTH_64_HEX_CHARS_HERE
   
   # ── Email via Mailpit (optional but useful) ──────────────
   SMTP_HOST=localhost
   SMTP_PORT=1026
   SMTP_FROM=noreply@orimora.local
   
   # ── Dev defaults ─────────────────────────────────────────
   NODE_ENV=development
   ALLOW_REGISTRATION=true

   Erzeuge vier unabhängige Geheimnisse (vier Mal ausführen):

   node -e "console.log(require('crypto').randomBytes(32).toString('hex'))"

5. Datenbank-Migrationen ausführen:

   yarn db:migrate

   Nach jedem git pull, der Dateien unter src/lib/server/db/migrations/ hinzufügt, wiederholen.

6. Dev-Server starten:

   yarn dev

7. App öffnen unter http://localhost:5173 und das Onboarding abschließen (legt deinen Workspace-Admin an).

8. Health prüfen:

   curl -s http://localhost:5173/api/health

   Magic-Link-E-Mails erscheinen im Mailpit-UI: http://localhost:9025

---

Weg B — Native Yarn (ohne Docker)

1. Voraussetzungen installieren:

   Werkzeug	Version
   Node.js	22 LTS oder 24
   Yarn	wie in den Repo-Skripten genutzt
   PostgreSQL	16+
   Redis	7+

2. Klonen und installieren (wie Weg A, Schritt 2).

3. PostgreSQL-Datenbank anlegen:

   createdb knowledgebase
   redis-cli ping   # must return PONG

4. .env konfigurieren — passe DATABASE_URL an deinen lokalen Postgres-Benutzer/-Passwort/-Port an (Standard-Port 5432, nicht 5433):

   DATABASE_URL=postgresql://YOUR_USER:YOUR_PASSWORD@localhost:5432/knowledgebase
   REDIS_URL=redis://localhost:6379
   APP_URL=http://localhost:5173
   # … same secrets as Path A

5. Migrieren, Dev-Server, prüfen — wie Weg A, Schritte 5–8.

---

Umgebungsvariablen — vollständige Referenz

Die kanonische Liste liegt in .env.example. Unten: jede Variable in verständlicher Sprache.

Hinweis

Ältere Doku erwähnte SECRET_KEY oder PUBLIC_BASE_URL. Die korrekten Namen sind SESSION_SECRET und APP_URL.

Pflicht für lokale Entwicklung — 7 Variablen

Minimum, um den Dev-Server zu booten.

Variable	Was sie tut	Beispiel / wie setzen
DATABASE_URL	PostgreSQL-Verbindungsstring	Weg A: postgresql://kb:kb_dev_password@localhost:5433/knowledgebase
REDIS_URL	Redis für Sessions, Queues, Rate Limits	redis://localhost:6379
APP_URL	Öffentliche URL der App (Magic Links, OAuth-Redirects)	http://localhost:5173 im Vite-Dev
SESSION_SECRET	Signiert HTTP-only-Session-Cookies (mind. 32 Bytes)	64 Hex-Zeichen via randomBytes(32)
MAGIC_LINK_SECRET	Signiert passwortlose Login-Tokens	Separater 64-Hex-Wert
LLM_ENCRYPTION_KEY	Verschlüsselt gespeicherte LLM-API-Keys at rest	64 Hex-Zeichen — auch nötig, wenn KI ungenutzt
PUBLISHING_ENCRYPTION_KEY	Verschlüsselt Webhook-Secrets und Publishing-Credentials	64 Hex-Zeichen

Docker-Compose-Helfer

Variable	Was sie tut	Standard
COMPOSE_FILE	Welche Compose-Datei docker compose lokal nutzt	docker-compose.yml (in .env.example gesetzt)

Optionale Auth-Härtung

Variable	Was sie tut	Standard wenn ungesetzt
API_KEY_SECRET	Hasht API-Keys at rest	MAGIC_LINK_SECRET
EMAIL_CHANGE_SECRET	Signiert E-Mail-Änderungs-Tokens	MAGIC_LINK_SECRET
ACCOUNT_DELETION_SECRET	Signiert Account-Löschungs-Tokens	SESSION_SECRET
SESSION_IDLE_TIMEOUT_DAYS	Loggt inaktive Sessions nach N Tagen aus; 0 = aus	7

OAuth (optional)

Registriere Redirect-URIs in der jeweiligen Provider-Konsole als {APP_URL}/auth/google/callback, /auth/microsoft/callback, /auth/oidc/callback.

Variable	Was sie tut
GOOGLE_CLIENT_ID / GOOGLE_CLIENT_SECRET	Google-Anmeldung
MICROSOFT_TENANT_ID	Azure-Tenant-ID oder common
MICROSOFT_CLIENT_ID / MICROSOFT_CLIENT_SECRET	Microsoft-Anmeldung
OIDC_ISSUER / OIDC_CLIENT_ID / OIDC_CLIENT_SECRET	Generisches OpenID Connect
OIDC_SCOPE	Leerzeichen-getrennte Scopes (Standard: openid email profile)

E-Mail / SMTP

Leer lassen, um E-Mail zu überspringen (stattdessen OAuth nutzen). Mit Mailpit (Weg A): SMTP_HOST=localhost, SMTP_PORT=1026.

Variable	Was sie tut
SMTP_HOST	Mailserver-Hostname
SMTP_PORT	Meist 587 (STARTTLS) oder 465
SMTP_USER / SMTP_PASSWORD	Zugangsdaten (leer für Mailpit)
SMTP_FROM	Absender-Adresse

App-Verhalten

Variable	Was sie tut	Standard
NODE_ENV	development oder production	development
ALLOW_REGISTRATION	Offene Registrierung erlauben	false in .env.example; lokal true nutzen
DOCS_URL	Redirect-Ziel für /docs in der App	https://docs.orimora.com
EXTRA_ALLOWED_ORIGINS	Zusätzliche erlaubte Origins für WebSocket /collab (komma-getrennt)	—

Kollaboration (Echtzeit-Bearbeitung)

Variable	Was sie tut	Standard
COLLAB_SECRET	Optionales geteiltes Secret für Collab-WebSocket	ungesetzt im Dev
COLLAB_MAX_CONNECTIONS	Max. gleichzeitige Collab-Verbindungen	50
COLLAB_MAX_YJS_STATE_BYTES	Max. persistierte Yjs-Dokumentgröße (DoS-Schutz)	8388608 (8 MB)

Echtzeit-Bearbeitung nutzt den WebSocket-Pfad /collab auf derselben Origin wie die App. Vite übernimmt das Upgrade im Dev.

Betrieb (meist Produktion)

Variable	Was sie tut
CRON_SECRET	Schützt POST /api/admin/cron.cleanup (Papierkorb-Bereinigung, Einladungs-Erinnerungen)
ORIMORA_API_KEY	Für lokales MCP-CLI (yarn mcp) — in Einstellungen → Entwickler anlegen

KI, S3, Backups, Push, Quotas

Gruppe	Variablen
KI & Publishing	LLM_ENCRYPTION_KEY, PUBLISHING_ENCRYPTION_KEY, GIT_MIRROR_ALLOWED_HOSTS
S3-Speicher (reserviert — noch nicht verdrahtet; Uploads nutzen das lokale orimora-uploads-Volume)	S3_BUCKET, S3_REGION, S3_ACCESS_KEY, S3_SECRET_KEY, S3_ENDPOINT
Backups	BACKUP_ENABLED, BACKUP_PATH, BACKUP_RETENTION_DAILY, BACKUP_RETENTION_WEEKLY, BACKUP_SCHEDULE, BACKUP_S3_BUCKET, BACKUP_PG_DUMP_TIMEOUT_MS
Web Push	VAPID_PUBLIC_KEY, VAPID_PRIVATE_KEY, VAPID_SUBJECT — erzeugen mit node scripts/generate-vapid-keys.mjs
Webhook-/Publishing-Tuning	WEBHOOK_*, PUBLISHING_* — siehe Konfiguration
Speicher-Quota	DEFAULT_TEAM_STORAGE_QUOTA_BYTES, STORAGE_QUOTA_WARN_PERCENT

---

Häufige Probleme

Symptom	Lösung
DATABASE_URL Verbindung abgelehnt	Weg A: docker compose up -d ausführen; Port 5433 statt 5432
Redis-Fehler	REDIS_URL prüfen; redis-cli ping
Migrationen schlagen fehl	Gleiche DATABASE_URL wie laufende App; DB-Benutzer braucht DDL-Rechte
Magic Link kommt nie an	SMTP konfigurieren oder Mailpit unter http://localhost:9025 öffnen
WebSocket / Collab schlägt fehl	Firewall muss WS zu APP_URL erlauben; EXTRA_ALLOWED_ORIGINS prüfen
Boot-Fehler zu Encryption Keys	Sowohl LLM_ENCRYPTION_KEY als auch PUBLISHING_ENCRYPTION_KEY setzen
401 auf /api/v1/*	Authorization: Bearer kb_… aus Einstellungen → Entwickler nutzen

Nächste Schritte

• Deployment — Produktions-Docker-Compose-Stack
• Coolify Setup — gehostetes Deployment mit Traefik
• Konfiguration — gruppierte Referenz mit OAuth-Redirect-Beispielen
• Editor — Dokumente schreiben und formatieren