Zum Inhalt springen

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.

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.


Wenn du einen KI-Coding-Agenten wie Claude Code nutzt, kann er das gesamte lokale Setup für dich erledigen — klonen, Secrets generieren, den Stack starten, Migrationen ausführen und verifizieren. Er führt einfach die Schritte aus diesem Guide aus; du behältst die Kontrolle und bestätigst jeden Befehl.

Öffne den Agenten in einem leeren Ordner und füge einen Prompt wie diesen ein:

Richte Orimora für die lokale Entwicklung auf diesem Rechner ein, genau nach dem
offiziellen Installations-Guide (Docs: guides/installation, Weg A — Docker Compose)
und .env.example:
1. Klone https://github.com/orimora-app/orimora.git und führe `yarn install` aus.
2. Erstelle .env aus .env.example. Generiere jedes erforderliche Secret
(SESSION_SECRET, MAGIC_LINK_SECRET, …) mit:
node -e "console.log(require('crypto').randomBytes(32).toString('hex'))"
3. Starte die Infrastruktur mit Docker Compose und führe dann die DB-Migrationen aus.
4. Verifiziere, dass die App gesund ist, und nenne mir die lokale URL und den Login.
Zeig mir jeden Befehl vor der Ausführung. Committe niemals .env oder ein Secret.

Du kannst eine KI auch bei einem Produktions-Deployment helfen lassen, aber geh mit großer Vor- und Umsicht vor: echte Secrets, eine produktive Datenbank und ein öffentlicher Origin sind im Spiel. Prüfe jeden Befehl, lass den Agenten niemals Produktions-Secrets generieren oder offenlegen, und verifiziere die Deployment-Schritte selbst, bevor du sie anwendest.


Weg A — Docker Compose (empfohlen)

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

    Terminal-Fenster
    docker compose version
  2. Repository klonen und Node-Abhängigkeiten installieren. Das Repo nutzt Yarn 1 (Classic) — eine frische Node-Installation bringt es nicht mit. Aktiviere es über corepack (bei Node 22/24 dabei); das packageManager-Feld des Repos pinnt automatisch die richtige Version:

    Terminal-Fenster
    git clone https://github.com/orimora-app/orimora.git orimora
    cd orimora
    corepack enable
    yarn install

    Installiere Yarn nicht über npm i -g yarn — das installiert Yarn 4, das das Yarn-Classic-Lockfile dieses Repos nicht lesen kann.

  3. .env-Datei anlegen (vor dem Docker-Start — sie sagt Compose auch, welche Datei gilt, und vermeidet so eine „multiple config files”-Warnung):

    Terminal-Fenster
    cp .env.example .env

    Die Vorlage passt bereits zum Docker-Dev-Stack (Datenbank-URL, Mailpit-Ports, Registrierung aktiv) — du musst nur die vier Geheimnisse eintragen. Zur Referenz die minimale, funktionierende Dev-Konfiguration:

    Terminal-Fenster
    # ── 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):

    Terminal-Fenster
    node -e "console.log(require('crypto').randomBytes(32).toString('hex'))"
  4. Infrastruktur starten (PostgreSQL, Redis, Mailpit):

    Terminal-Fenster
    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

    Port schon belegt? Jeder Host-Port ist per .env überschreibbar — z. B. POSTGRES_HOST_PORT=5544 (dann den Port in DATABASE_URL mit anpassen), REDIS_HOST_PORT, MAILPIT_SMTP_PORT, MAILPIT_UI_PORT.

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

  5. Datenbank-Migrationen ausführen:

    Terminal-Fenster
    yarn db:migrate

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

  6. Dev-Server starten:

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

  8. Health prüfen:

    Terminal-Fenster
    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 1.22 (Classic) — corepack enable, nicht npm i -g yarn
    PostgreSQL 16+
    Redis 7+
  2. Klonen und installieren (wie Weg A, Schritt 2).

  3. PostgreSQL-Datenbank anlegen:

    Terminal-Fenster
    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):

    Terminal-Fenster
    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.


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

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

Die Anmeldung läuft über einen Link per E-Mail. Der erste Login braucht deshalb einen funktionierenden Mailserver (die SMTP_*-Variablen) oder Single Sign-on, eingerichtet über die Umgebungsvariablen. Ohne eines von beiden kommt niemand hinein. Die App sagt das im Start-Log und auf der Login-Seite. 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

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
  • Deployment — Produktions-Docker-Compose-Stack
  • Coolify Setup — gehostetes Deployment mit Traefik
  • Konfiguration — gruppierte Referenz mit OAuth-Redirect-Beispielen
  • Editor — Dokumente schreiben und formatieren