Owlat Docs

ADR-006: Self-Hosted Convex

Why Owlat uses the open-source Convex backend for self-hosting instead of migrating to a different database.

  • Status: Accepted
  • Date: 2026-03-24

Context

Owlat's backend runs entirely on Convex (ADR-002). As the platform grows, self-hosting becomes a requirement for organizations that need data sovereignty, compliance with on-premises mandates, or full control over their infrastructure.

The options considered:

  1. Migrate to PostgreSQL + custom API layer — rewrite all Convex queries, mutations, and actions into a traditional REST/tRPC backend with PostgreSQL. Full control, but massive migration effort and loss of real-time reactivity, ACID transactions, and the co-located TypeScript function model.
  2. Abstract with a database adapter layer — maintain both Convex (cloud) and PostgreSQL (self-hosted) behind an interface. Doubles the maintenance surface and testing matrix for every feature.
  3. Use the open-source Convex backend — Convex open-sourced their backend under the MIT license. Self-hosters run the same Convex runtime via Docker. Zero code changes to the application layer.

Decision

Use the open-source Convex backend for self-hosting. The entire Owlat stack — API, real-time subscriptions, file storage, vector search, scheduled functions — runs identically whether deployed to Convex Cloud or self-hosted via Docker.

Key properties of self-hosted Convex:

  • Docker deployment — single container for the backend, with an optional dashboard container for administration
  • Built-in storage — file uploads via ctx.storage work without an external S3 service
  • Built-in vector search — vectorIndex definitions work natively, enabling the Knowledge Graph and semantic file search without a separate vector database
  • Full CLI support — npx convex dev and npx convex deploy work against self-hosted instances via CONVEX_SELF_HOSTED_URL
  • MIT license — no usage restrictions, no license fees

Consequences

Enables:

  • Zero application code changes for self-hosting — the same apps/api/convex/ functions run on both cloud and self-hosted
  • Single Docker Compose file for the entire Owlat stack (Convex, web, MTA, Redis, ClamAV)
  • Vector search for the Knowledge Graph and semantic file system without deploying a separate vector database
  • File storage without deploying MinIO or S3
  • Data sovereignty — all data stays within the self-hoster's infrastructure

Trade-offs:

  • Self-hosters take on operational responsibility for the Convex backend (backups, upgrades, monitoring)
  • Self-hosted Convex supports free-tier features of the cloud product — some advanced cloud features may not be available
  • Requires Docker and sufficient compute resources for the Convex runtime
  • Community support for self-hosted issues (via Discord #self-hosted channel) rather than enterprise SLA
Next ADR-007: Pluggable LLM Provider