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-Anwendung

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 Cache

Datenbank und Redis

Variable	Pflicht	Beschreibung
DATABASE_URL	Ja	PostgreSQL-16+-Verbindungsstring.
REDIS_URL	Ja	Für Sessions, Rate Limiting, Queues und BullMQ-Worker.

Authentifizierungs-Secrets

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:

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 und öffentliche URLs

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.

E-Mail (Magic Link)

SMTP-Einstellungen

Wenn SMTP ungesetzt ist, wird keine Magic-Link-E-Mail gesendet (im Dev OAuth oder eine andere Strategie nutzen).

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

OAuth

Google, Microsoft, OIDC

Google

Variable	Beschreibung
GOOGLE_CLIENT_ID	OAuth-Client-ID
GOOGLE_CLIENT_SECRET	OAuth-Client-Secret

Redirect: {APP_URL}/auth/google/callback

Microsoft Entra ID

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

Generisches OIDC

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

Kollaboration (Yjs / Hocuspocus)

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.

MCP OAuth (Claude Mobile / Custom Connectors)

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	HMAC-Secret zum Hashen von OAuth-Codes/Tokens at rest. In Produktion einen eigenen 64-Zeichen-Wert setzen.

Objektspeicher, KI, Publishing, Push, Quota, Cron

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.

Team-Einstellungen (HTTP-API)

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

S3-Objektspeicher

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:

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.

Sicherheitshinweise

Achtung

Bewahre SESSION_SECRET, MAGIC_LINK_SECRET, LLM_ENCRYPTION_KEY und Datenbank-Zugangsdaten in Produktion in einem Secret Manager auf. Committe .env niemals.

Siehe auch

• Installation — Checkliste für lokale Entwicklung
• Deployment — Docker Compose und Migrationen
• Coolify Setup — Produktions-Env-Checkliste
• REST-API-Überblick — Bearer-Keys und Rate Limits