ADR-006: Selbst gehostetes Convex

• Status: Angenommen
• Datum: 2026-03-24

Kontext

Owlats Backend läuft vollständig auf Convex (ADR-002). Mit dem Wachstum der Plattform wird Self-Hosting zur Anforderung für Organisationen, die Datensouveränität, die Einhaltung von On-Premises-Vorgaben oder volle Kontrolle über ihre Infrastruktur benötigen.

Die geprüften Optionen:

1. Migration auf PostgreSQL + eigene API-Schicht — alle Convex-Queries, -Mutations und -Actions in ein klassisches REST-/tRPC-Backend mit PostgreSQL umschreiben. Volle Kontrolle, aber enormer Migrationsaufwand und Verlust von Echtzeitreaktivität, ACID-Transaktionen und dem Modell koresidenter TypeScript-Funktionen.
2. Abstraktion über eine Datenbank-Adapterschicht — sowohl Convex (Cloud) als auch PostgreSQL (selbst gehostet) hinter einem Interface pflegen. Verdoppelt die Wartungsfläche und die Testmatrix für jedes Feature.
3. Das quelloffene Convex-Backend nutzen — Convex hat sein Backend quelloffen gestellt, und zwar unter der Functional Source License (FSL-1.1-Apache-2.0), die zwei Jahre nach jedem Release in Apache 2.0 übergeht. Selbst-Hoster betreiben dieselbe Convex-Runtime per Docker. Keinerlei Codeänderungen auf Anwendungsebene.

Entscheidung

Das quelloffene Convex-Backend für das Self-Hosting nutzen. Der gesamte Owlat-Stack — API, Echtzeit-Subscriptions, Dateispeicher, Vektorsuche, geplante Funktionen — läuft identisch, ob in der Convex Cloud deployt oder per Docker selbst gehostet.

Zentrale Eigenschaften von selbst gehostetem Convex:

• Docker-Deployment — ein einzelner Container für das Backend, dazu optional ein Dashboard-Container für die Administration
• Integrierter Speicher — Datei-Uploads über ctx.storage funktionieren ohne externen S3-Dienst
• Integrierte Vektorsuche — vectorIndex-Definitionen funktionieren nativ und ermöglichen den Knowledge Graph und die semantische Dateisuche ohne separate Vektordatenbank
• Volle CLI-Unterstützung — npx convex dev und npx convex deploy funktionieren über CONVEX_SELF_HOSTED_URL auch gegen selbst gehostete Instanzen
• FSL-Lizenz — Functional Source License (nach zwei Jahren Apache 2.0); kostenlos selbst zu hosten und intern zu nutzen, keine Lizenzgebühren, mit einer befristeten Einschränkung beim Weiterverkauf von Convex selbst

Konsequenzen

Ermöglicht:

• Keine Änderungen am Anwendungscode für das Self-Hosting — dieselben Funktionen aus apps/api/convex/ laufen in der Cloud wie selbst gehostet
• Eine einzige Docker-Compose-Datei für den gesamten Owlat-Stack (Convex, Web, MTA, Redis, ClamAV)
• Vektorsuche für den Knowledge Graph und das semantische Dateisystem, ohne eine separate Vektordatenbank zu deployen
• Dateispeicher, ohne MinIO oder S3 zu deployen
• Datensouveränität — alle Daten bleiben innerhalb der Infrastruktur des Selbst-Hosters

Abwägungen:

• Selbst-Hoster übernehmen die operative Verantwortung für das Convex-Backend (Backups, Upgrades, Monitoring)
• Selbst gehostetes Convex unterstützt die Free-Tier-Funktionen des Cloud-Produkts — einige fortgeschrittene Cloud-Funktionen stehen möglicherweise nicht zur Verfügung
• Erfordert Docker und ausreichende Rechenressourcen für die Convex-Runtime
• Community-Support für Self-Hosting-Probleme (über den Discord-Kanal #self-hosted) statt eines Enterprise-SLA