Zum Inhalt springen
Orimora Docs

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?

Abschnitt betitelt „Welcher Weg passt?“
WegFür wenWas du installierst
A — Docker Compose (empfohlen)Einsteiger, schneller StartNur Docker Desktop — Postgres, Redis und Mailpit starten automatisch
B — Native YarnAktive Entwicklung am CodeNode.js 22+, Yarn, PostgreSQL 16+, Redis 7+ auf deinem Rechner

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

Installation mit KI (Claude Code)

Abschnitt betitelt „Installation mit KI (Claude Code)“

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:

    DienstZweckHost-Port
    postgresDatenbank5433 → Container 5432
    redisSessions, Queues, Rate Limits6379
    mailpitFä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:

    WerkzeugVersion
    Node.js22 LTS oder 24
    Yarn1.22 (Classic) — corepack enable, nicht npm i -g yarn
    PostgreSQL16+
    Redis7+

  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.

Umgebungsvariablen — vollständige Referenz

Abschnitt betitelt „Umgebungsvariablen — vollständige Referenz“

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.

VariableWas sie tutBeispiel / wie setzen
DATABASE_URLPostgreSQL-VerbindungsstringWeg A: postgresql://kb:kb_dev_password@localhost:5433/knowledgebase
REDIS_URLRedis für Sessions, Queues, Rate Limitsredis://localhost:6379
APP_URLÖffentliche URL der App (Magic Links, OAuth-Redirects)http://localhost:5173 im Vite-Dev
SESSION_SECRETSigniert HTTP-only-Session-Cookies (mind. 32 Bytes)64 Hex-Zeichen via randomBytes(32)
MAGIC_LINK_SECRETSigniert passwortlose Login-TokensSeparater 64-Hex-Wert
LLM_ENCRYPTION_KEYVerschlüsselt gespeicherte LLM-API-Keys at rest64 Hex-Zeichen — auch nötig, wenn KI ungenutzt
PUBLISHING_ENCRYPTION_KEYVerschlüsselt Webhook-Secrets und Publishing-Credentials64 Hex-Zeichen
Docker-Compose-Helfer
VariableWas sie tutStandard
COMPOSE_FILEWelche Compose-Datei docker compose lokal nutztdocker-compose.yml (in .env.example gesetzt)
Optionale Auth-Härtung
VariableWas sie tutStandard wenn ungesetzt
API_KEY_SECRETHasht API-Keys at restMAGIC_LINK_SECRET
EMAIL_CHANGE_SECRETSigniert E-Mail-Änderungs-TokensMAGIC_LINK_SECRET
ACCOUNT_DELETION_SECRETSigniert Account-Löschungs-TokensSESSION_SECRET
SESSION_IDLE_TIMEOUT_DAYSLoggt inaktive Sessions nach N Tagen aus; 0 = aus7
OAuth (optional)

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

VariableWas sie tut
GOOGLE_CLIENT_ID / GOOGLE_CLIENT_SECRETGoogle-Anmeldung
MICROSOFT_TENANT_IDAzure-Tenant-ID oder common
MICROSOFT_CLIENT_ID / MICROSOFT_CLIENT_SECRETMicrosoft-Anmeldung
OIDC_ISSUER / OIDC_CLIENT_ID / OIDC_CLIENT_SECRETGenerisches OpenID Connect
OIDC_SCOPELeerzeichen-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.

VariableWas sie tut
SMTP_HOSTMailserver-Hostname
SMTP_PORTMeist 587 (STARTTLS) oder 465
SMTP_USER / SMTP_PASSWORDZugangsdaten (leer für Mailpit)
SMTP_FROMAbsender-Adresse
App-Verhalten
VariableWas sie tutStandard
NODE_ENVdevelopment oder productiondevelopment
ALLOW_REGISTRATIONOffene Registrierung erlaubenfalse in .env.example; lokal true nutzen
DOCS_URLRedirect-Ziel für /docs in der Apphttps://docs.orimora.com
EXTRA_ALLOWED_ORIGINSZusätzliche erlaubte Origins für WebSocket /collab (komma-getrennt)—
Kollaboration (Echtzeit-Bearbeitung)
VariableWas sie tutStandard
COLLAB_SECRETOptionales geteiltes Secret für Collab-WebSocketungesetzt im Dev
COLLAB_MAX_CONNECTIONSMax. gleichzeitige Collab-Verbindungen50
COLLAB_MAX_YJS_STATE_BYTESMax. 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)
VariableWas sie tut
CRON_SECRETSchützt POST /api/admin/cron.cleanup (Papierkorb-Bereinigung, Einladungs-Erinnerungen)
ORIMORA_API_KEYFür lokales MCP-CLI (yarn mcp) — in Einstellungen → Entwickler anlegen
KI, S3, Backups, Push, Quotas
GruppeVariablen
KI & PublishingLLM_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
BackupsBACKUP_ENABLED, BACKUP_PATH, BACKUP_RETENTION_DAILY, BACKUP_RETENTION_WEEKLY, BACKUP_SCHEDULE, BACKUP_S3_BUCKET, BACKUP_PG_DUMP_TIMEOUT_MS
Web PushVAPID_PUBLIC_KEY, VAPID_PRIVATE_KEY, VAPID_SUBJECT — erzeugen mit node scripts/generate-vapid-keys.mjs
Webhook-/Publishing-TuningWEBHOOK_*, PUBLISHING_* — siehe Konfiguration
Speicher-QuotaDEFAULT_TEAM_STORAGE_QUOTA_BYTES, STORAGE_QUOTA_WARN_PERCENT

Häufige Probleme

Abschnitt betitelt „Häufige Probleme“
SymptomLösung
DATABASE_URL Verbindung abgelehntWeg A: docker compose up -d ausführen; Port 5433 statt 5432
Redis-FehlerREDIS_URL prüfen; redis-cli ping
Migrationen schlagen fehlGleiche DATABASE_URL wie laufende App; DB-Benutzer braucht DDL-Rechte
Magic Link kommt nie anSMTP konfigurieren oder Mailpit unter http://localhost:9025 öffnen
WebSocket / Collab schlägt fehlFirewall muss WS zu APP_URL erlauben; EXTRA_ALLOWED_ORIGINS prüfen
Boot-Fehler zu Encryption KeysSowohl LLM_ENCRYPTION_KEY als auch PUBLISHING_ENCRYPTION_KEY setzen
401 auf /api/v1/*Authorization: Bearer kb_… aus Einstellungen → Entwickler nutzen

Nächste Schritte

Abschnitt betitelt „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