Deployment

Diese Seite entspricht docker-compose.prod.yml und .env.example im Repository. Für lokale Entwicklung im Alltag: Installation.

Voraussetzungen

Abhängigkeit	Minimum
Docker	24+
Docker Compose v2	2.20+
RAM (App + Postgres + Redis)	2 GB empfohlen (1 GB Minimum ist knapp)

TLS-Terminierung erfolgt üblicherweise über einen Reverse Proxy (Nginx, Traefik, Caddy) oder deine Plattform (Coolify, Kubernetes Ingress).

Schnellstart

1. Klonen und konfigurieren

git clone https://github.com/defcon1702/orimora.git orimora
cd orimora
cp .env.example .env

Setze alle als erforderlich markierten Variablen in .env. Das Compose-File erwartet mindestens:

• APP_URL — öffentliche HTTPS-URL, z. B. https://wiki.example.com
• POSTGRES_PASSWORD — ein starker Zufallswert (wird in DATABASE_URL interpoliert)
• SESSION_SECRET, MAGIC_LINK_SECRET, LLM_ENCRYPTION_KEY — 64-stellige Hex-Strings (je 32 Byte)

2. Secrets erzeugen

Nutze dasselbe Muster wie im Root-DEPLOYMENT.md:

node -e "console.log(require('crypto').randomBytes(32).toString('hex'))"   # für jedes *64-Hex*-Secret wiederholen

Bewahre die erzeugten Werte in einem Passwortmanager auf; committe .env niemals.

3. Bauen und starten

docker compose -f docker-compose.prod.yml up -d --build

4. Datenbank-Migrationen ausführen

Erforderlich beim ersten Deploy und nach Upgrades, die neue Migrationsdateien mitbringen:

docker compose -f docker-compose.prod.yml exec app yarn db:migrate

5. Verifizieren

curl -s http://localhost:3000/api/ready

Öffne dann APP_URL im Browser und schließe das Onboarding ab, falls dies eine frische Datenbank ist.

Hinweis

Health-Probes. /api/live ist eine reine Liveness-Prüfung (immer 200, solange der Prozess läuft — nutze sie für die Entscheidung, ob der Container neu gestartet werden soll). /api/ready prüft die Datenbank und Redis und liefert 503, wenn eines ausfällt — nutze sie für Load-Balancer-/Orchestrator-Routing. Der Docker-Health-Check verwendet /api/ready. (/api/health bleibt aus Kompatibilitätsgründen erhalten.)

Tipp

Wenn du Coolify mit mehreren Services auf einem Host nutzt (Marketing, Docs, App), siehe Coolify Setup für Traefik-Pfad-Prioritäten und Labels.

Umgebungsvariablen (Produktion)

Die folgende Tabelle deckt sich mit .env.example. Die Variablennamen unterscheiden sich von älteren Entwürfen, die SECRET_KEY oder PUBLIC_BASE_URL verwendeten.

Pflicht (typische Produktion)

Variable	Zweck
APP_URL	Kanonische öffentliche URL — genutzt in Links, OAuth-Redirects, Magic-Link-URLs
DATABASE_URL	In Compose automatisch aus POSTGRES_* gesetzt; eigene Installs müssen auf PostgreSQL 16+ zeigen
REDIS_URL	Zeigt auf den mitgelieferten redis-Service in Compose (redis://redis:6379, kein Passwort)
SESSION_SECRET	Signiert Session-Cookies
MAGIC_LINK_SECRET	Signiert Magic-Link-Tokens
LLM_ENCRYPTION_KEY	AES-256-GCM für gespeicherte LLM-API-Keys (erforderlich, auch wenn KI deaktiviert ist)
POSTGRES_PASSWORD	Passwort des Datenbank-Nutzers (Compose)

Optional, aber gebräuchlich

Variable	Zweck
CRON_SECRET	Bearer-Token für POST /api/admin/cron.cleanup (geplanter Trash-Purge, Erinnerungen)
COLLAB_SECRET	Shared Secret für Yjs-/Hocuspocus-Kollaboration
COLLAB_MAX_CONNECTIONS	Begrenzt gleichzeitige Collab-Sockets (Default 50)
SMTP_*	Ausgehende E-Mail für Magic Links (SMTP_PASSWORD in .env.example)
GOOGLE_CLIENT_ID / GOOGLE_CLIENT_SECRET	Google OAuth
OIDC_*	Generischer OIDC-Provider
STORAGE_DRIVER / S3_*	Upload-Speicher-Backend. Default local (Platte). STORAGE_DRIVER=s3 + S3_BUCKET/S3_ACCESS_KEY/S3_SECRET_KEY (+ optional S3_ENDPOINT/S3_FORCE_PATH_STYLE/S3_PRESIGN_TTL_SECONDS) speichert Anhänge/Avatare/Logos in einem S3-kompatiblen Bucket, ausgeliefert über presigned URLs — siehe Konfiguration. (Getrennt von Off-Site-Backups, die BACKUP_RCLONE_REMOTE nutzen; BACKUP_S3_BUCKET ist geparst, aber nicht verdrahtet.)

Vollständige Spaltenreferenz: DEPLOYMENT.md im Repo.

Reverse Proxy

Terminiere TLS an Nginx, Caddy oder Traefik und leite zum App-Container weiter (Port 3000 innerhalb des Netzwerks). Du musst erhalten:

• Host
• X-Forwarded-For
• X-Forwarded-Proto (HTTPS-Erkennung)
• WebSocket-Upgrade-Header für /collab

Beispiel-Nginx-Location (HTTP → App):

location / {
    proxy_pass http://127.0.0.1:3000;
    proxy_http_version 1.1;
    proxy_set_header Upgrade $http_upgrade;
    proxy_set_header Connection "upgrade";
    proxy_set_header Host $host;
    proxy_set_header X-Real-IP $remote_addr;
    proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
    proxy_set_header X-Forwarded-Proto $scheme;
}

Updates

git pull
docker compose -f docker-compose.prod.yml build app
docker compose -f docker-compose.prod.yml up -d
docker compose -f docker-compose.prod.yml exec app yarn db:migrate

Beobachte die Anwendungslogs während des ersten Requests nach einer Schema-Änderung.

Backups & Notfallwiederherstellung

Betreibe Produktion nicht ohne Backups. BACKUP_ENABLED ist im Produktions-Compose-File standardmäßig true (tägliche verschlüsselte DB-Dumps + wöchentliche Markdown-Exporte), aber du musst trotzdem:

1. CRON_SECRET setzen (treibt die geplanten Backup- + Cleanup-Jobs).
2. Ein Off-Site-Ziel (BACKUP_RCLONE_REMOTE) konfigurieren, damit ein Host-Verlust nicht alles verliert.
3. Den Recovery-Code sichern (einmalig unter Einstellungen → Admin → Backups angezeigt) — Off-Site-Kopien sind verschlüsselt und ohne ihn nicht zu entschlüsseln.

Probe dann eine Wiederherstellung. Siehe Backups und das Notfallwiederherstellungs-Runbook.

Fehlerbehebung

Problem	Prüfungen
OAuth-Redirect-Mismatch	APP_URL muss exakt mit der URL in der Google-/OIDC-Konsole übereinstimmen
Redis-Verbindungsfehler	REDIS_URL erreichbar; redis-Container healthy
502 vom Proxy	App lauscht nicht auf erwartetem Port; WebSocket-Pfad blockiert
Migration schlägt fehl	DB zuerst sichern; sicherstellen, dass nur ein Migration-Runner gleichzeitig läuft

Weiterführend

• Konfiguration — SMTP, KI, S3, MCP OAuth
• Backups · Notfallwiederherstellung — verschlüsselte Off-Site-Backups + Restore
• REST-API Überblick — Rate-Limits und Auth
• Architektur — Stack-Überblick