Zum Inhalt springen

Konfiguration

Orimora wird vollständig über Umgebungsvariablen konfiguriert (sowie über Team-Einstellungen in der Datenbank). Die Quelle der Wahrheit ist .env.example im Repo-Root; klappe jeden Abschnitt unten für die vollständige Tabelle auf.

Kern-Anwendungsvariablen
Variable Pflicht Beschreibung
APP_URL Ja (Prod) Öffentliche Basis-URL, z. B. https://wiki.example.com. Treibt Magic Links und OAuth-Redirects. Dev: http://localhost:5173.
NODE_ENV — development oder production.
PORT — HTTP-Listen-Port (Standard 3000 in Docker; Vite-Dev nutzt seinen eigenen Port).
Datenbank und Redis
Variable Pflicht Beschreibung
DATABASE_URL Ja PostgreSQL-16+-Verbindungsstring.
REDIS_URL Ja Für Sessions, Rate Limiting, Queues und BullMQ-Worker.
Session- und Magic-Link-Secrets
Variable Pflicht Beschreibung
SESSION_SECRET Ja 64 Hex-Zeichen (32 Bytes). Signiert Session-Cookies.
MAGIC_LINK_SECRET Ja 64 Hex-Zeichen. Signiert Magic-Link-JWTs.

Erzeuge beide mit:

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

Optionale dedizierte HMAC-Secrets (in Produktion für unabhängige Rotation empfohlen):

Variable Standard wenn ungesetzt Zweck
API_KEY_SECRET MAGIC_LINK_SECRET Hasht API-Key-Tokens at rest
EMAIL_CHANGE_SECRET MAGIC_LINK_SECRET Signiert E-Mail-Änderungs-Bestätigungstokens
ACCOUNT_DELETION_SECRET SESSION_SECRET Signiert Account-Löschungs-Bestätigungstokens
Variable Standard Beschreibung
SESSION_IDLE_TIMEOUT_DAYS 7 Invalidiert Sessions nach so vielen inaktiven Tagen. 0 deaktiviert den Idle-Ablauf.
Registrierung, Docs-Redirect, CORS
Variable Standard Beschreibung
ALLOW_REGISTRATION false Bei false können nur eingeladene Nutzer beitreten (offene Registrierung deaktiviert).
DOCS_URL https://docs.orimora.com Wohin die App /docs-Anfragen umleitet (Starlight-Seite).
EXTRA_ALLOWED_ORIGINS — Komma-getrennte zusätzliche Origins für WebSocket /collab und Origin-Checks.
SMTP-Einstellungen

Wenn SMTP ungesetzt ist, wird keine Magic-Link-E-Mail gesendet. 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. Ist kein echter SMTP-Server konfiguriert, werden E-Mail-abhängige Aktionen in der App — Magic-Link-Login, Einladungen und E-Mail-Änderungen — in der Oberfläche deaktiviert (mit einem Hinweis, SMTP einzurichten), statt still fehlzuschlagen. Ein Systemadministrator kann unter Einstellungen → Admin einen Live-Verbindungstest ausführen.

Variable Beschreibung
SMTP_HOST Server-Hostname
SMTP_PORT Meist 587 (STARTTLS) oder 465
SMTP_USER Benutzername
SMTP_PASSWORD Passwort (Name in .env.example)
SMTP_FROM Absender-Adresse
Google, Microsoft, OIDC
Variable Beschreibung
GOOGLE_CLIENT_ID OAuth-Client-ID
GOOGLE_CLIENT_SECRET OAuth-Client-Secret

Redirect: {APP_URL}/auth/google/callback

Variable Beschreibung
MICROSOFT_TENANT_ID Tenant-ID oder common für Multi-Tenant
MICROSOFT_CLIENT_ID Application- (Client-) ID
MICROSOFT_CLIENT_SECRET Client-Secret

Redirect: {APP_URL}/auth/microsoft/callback

Variable Beschreibung
OIDC_ISSUER Issuer-URL
OIDC_CLIENT_ID Client-ID
OIDC_CLIENT_SECRET Client-Secret
OIDC_SCOPE Leerzeichen-getrennte Scopes (Standard openid email profile)

Redirect: {APP_URL}/auth/oidc/callback

WebSocket-/collab-Einstellungen
Variable Beschreibung
COLLAB_SECRET Optionales geteiltes Secret für den Collab-Endpunkt
COLLAB_MAX_CONNECTIONS Max. gleichzeitige WebSocket-Verbindungen
COLLAB_MAX_YJS_STATE_BYTES Max. persistierte Yjs-State-Größe pro Dokument (Standard 8 MB). 0 deaktiviert den Service-Layer-Check.
OAuth 2.1 + Dynamic Client Registration für den MCP-Endpunkt

Ermöglicht der Claude-Mobile-App und claude.ai Custom Connectors die Autorisierung gegen /api/mcp über einen Browser-OAuth-Flow, zusätzlich zu den bestehenden kb_…-API-Keys (die unverändert bleiben). Nutzerseitiges Setup im MCP-Guide.

Der OAuth-Issuer ist APP_URL — setze ihn vor dem Aktivieren in Produktion auf deine öffentliche https-Origin, sonst gibt die Discovery unbrauchbare localhost-URLs aus (der Server warnt beim Start).

Variable Standard Beschreibung
MCP_OAUTH_ENABLED true Hauptschalter. Bei false liefern die .well-known/oauth-*-Routen 404 und der Server gilt als Bearer-only.
MCP_OAUTH_ALLOWED_APP_SCHEMES claude:// Komma-getrennte Custom-Redirect-Schemes, die bei der Registrierung akzeptiert werden (neben https und http://localhost).
MCP_OAUTH_CORS_ORIGINS https://claude.ai,https://www.claude.ai Browser-Origins, die die OAuth-+MCP-Oberfläche cross-origin aufrufen dürfen.
MCP_OAUTH_ACCESS_TOKEN_TTL_SECONDS 3600 Lebensdauer des Access-Tokens.
MCP_OAUTH_REFRESH_TOKEN_TTL_SECONDS 2592000 Lebensdauer des Refresh-Tokens (30 Tage).
MCP_OAUTH_AUTH_CODE_TTL_SECONDS 60 Lebensdauer des Authorization-Codes.
OAUTH_REGISTER_RATE_LIMIT_PER_HOUR 10 Pro-IP-Limit für Dynamic Client Registration (/oauth/register).
MCP_OAUTH_TOKEN_SECRET API_KEY_SECRET → MAGIC_LINK_SECRET HMAC-Secret zum Hashen von OAuth-Codes/Tokens at rest. Nicht erforderlich — fällt auf API_KEY_SECRET, dann MAGIC_LINK_SECRET (immer gesetzt) zurück, OAuth funktioniert also ohne zusätzlichen Key. In Produktion einen eigenen 64-Zeichen-Wert für Blast-Radius-Trennung setzen.
Optionale Dienste und Verschlüsselungsschlüssel
Bereich Variablen
Upload-Speicher (Opt-in: STORAGE_DRIVER=s3; Default local) STORAGE_DRIVER, S3_BUCKET, S3_REGION, S3_ACCESS_KEY, S3_SECRET_KEY, S3_ENDPOINT, S3_FORCE_PATH_STYLE, S3_PRESIGN_TTL_SECONDS — siehe unten
KI LLM_ENCRYPTION_KEY (erforderlich) — KI-Assistent
Publishing PUBLISHING_ENCRYPTION_KEY (erforderlich), GIT_MIRROR_ALLOWED_HOSTS
Web Push VAPID_PUBLIC_KEY, VAPID_PRIVATE_KEY, VAPID_SUBJECT — aktiviert den Push-Kanal. Schritt-für-Schritt-Setup + Schlüsselerzeugung: Benachrichtigungen → Web-Push einrichten
Speicher-Quota DEFAULT_TEAM_STORAGE_QUOTA_BYTES, STORAGE_QUOTA_WARN_PERCENT
Backups BACKUP_ENABLED, BACKUP_PATH, BACKUP_SCHEDULE, BACKUP_RETENTION_DAILY/WEEKLY, BACKUP_S3_BUCKET, BACKUP_PG_DUMP_TIMEOUT_MS
Off-Site DR BACKUP_RCLONE_REMOTE, BACKUP_POST_HOOK — verschlüsselte Off-Site-Kopien, siehe Backups + Notfallwiederherstellung
Cron CRON_SECRET für POST /api/admin/cron.cleanup — in Produktion erforderlich (treibt geplante Cleanups + Einladungs-Erinnerungen)
Observability METRICS_TOKEN (Prometheus /api/metrics); SENTRY_DSN, SENTRY_ENVIRONMENT, SENTRY_RELEASE (Error-Tracking — siehe unten)
MCP CLI ORIMORA_API_KEY — siehe MCP-Guide

Webhook-/Publishing-Auto-Pause-Schwellenwerte (WEBHOOK_*, PUBLISHING_*) und SESSION_IDLE_TIMEOUT_DAYS sind inline in .env.example dokumentiert.

Error-Tracking. Setze SENTRY_DSN, um unerwartete 5xx-Serverfehler und SSO-Authentifizierungsfehler an ein beliebiges Sentry-kompatibles Backend weiterzuleiten — sentry.io, ein selbst gehostetes Sentry oder GlitchTip funktionieren alle, wobei sich nur die DSN ändert (kein Vendor-Lock-in). Reguläre 4xx werden nie gesendet, und E-Mail-Adressen sowie Token-artige Strings werden aus den Payloads entfernt. Leer lassen zum Deaktivieren. SENTRY_ENVIRONMENT nutzt standardmäßig NODE_ENV; SENTRY_RELEASE (z. B. ein Git-SHA) gruppiert Issues nach Version. Der Metrics-Endpunkt, die Health-Probes, das Error-Tracking und die Correlation-IDs sind gemeinsam unter Observability beschrieben.

Einige Defaults werden pro Team in der Datenbank gespeichert (Dokumentbreite, Locale, Revisions-Aufbewahrung). Siehe die Admin-Einstellungs-UI und REST-API-Überblick.

Standardmäßig werden Uploads (Dokument-Anhänge, Avatare, Team-Logos) auf der Platte unter ./uploads gespeichert und von der App ausgeliefert. Mit STORAGE_DRIVER=s3 landen sie stattdessen in einem S3-kompatiblen Bucket — AWS S3, MinIO, Cloudflare R2 oder Backblaze B2.

Variable Zweck
STORAGE_DRIVER local (Default) oder s3
S3_BUCKET Bucket-Name (Pflicht bei s3)
S3_ACCESS_KEY / S3_SECRET_KEY Zugangsdaten (Pflicht bei s3)
S3_REGION Region (Default us-east-1)
S3_ENDPOINT Custom-Endpunkt für Nicht-AWS-S3 (MinIO/R2/B2); leer = echtes AWS S3
S3_FORCE_PATH_STYLE true für MinIO und manche Self-Hosted-Gateways
S3_PRESIGN_TTL_SECONDS Lebensdauer der presigned GET-URLs (Default 300)

Der Bucket bleibt privat — Dateien werden über kurzlebige presigned URLs ausgeliefert, auf die die Upload-Routen nach derselben Berechtigungsprüfung wie im lokalen Pfad weiterleiten (Anhänge eines restricted Dokuments bleiben also geschützt). In Produktion ist STORAGE_DRIVER=s3 mit fehlendem Bucket oder fehlenden Zugangsdaten ein harter Start-Fehler statt eines stillen Fallbacks.

Verwaiste Objekte (durch ein selten fehlgeschlagenes Delete zurückgelassen) werden vom geplanten Cleanup-Cron aufgeräumt, konservativ: nur Objekte, die keine Zeile referenziert und die älter als 24 h sind, werden entfernt — eine gerade hochgeladene Datei wird also nie gelöscht.

Den Treiber zur Deploy-Zeit setzen, nicht auf einer laufenden Instanz. Ein Wechsel local → s3 macht bestehende Platten-Dateien unerreichbar (jedes vorhandene Bild liefert 404), bis sie in den Bucket nachgeladen wurden; der Treiber wird nie automatisch aus S3_* erkannt.

Eine bestehende Instanz migrieren. Mit gesetzten S3_* (der Treiber darf local bleiben) zuerst die vorhandenen Uploads in den Bucket kopieren:

Terminal-Fenster
yarn storage:migrate-s3 # Probelauf — zeigt, was kopiert würde
yarn storage:migrate-s3 --apply # hochladen

Der Lauf ist idempotent (erneut ausführen, um neu hinzugekommene Dateien zu erfassen) und nicht-destruktiv (lokale Dateien werden nur gelesen). Sobald er Erfolg meldet, STORAGE_DRIVER=s3 setzen und neu deployen. Zum Zurückrollen wieder auf local setzen — die lokalen Dateien bleiben unangetastet.