Add production support for SQLite

README.md

@@ -7,10 +7,10 @@ organised in private **vaults** (each vault is the web equivalent of one XCA
 database).
 
 - **`server/`** — Python + [kaya](https://github.com/woggioni/kaya) backend:
-  OIDC login, Redis sessions, personal API tokens, Postgres (Tortoise ORM +
-  aerich migrations), AES-256-GCM private-key encryption, and a complete REST
-  API. The pure PKI domain logic lives in `packages/kca-core`; the deployable
-  app is `packages/kca-app`.
+  OIDC login, Redis sessions, personal API tokens, PostgreSQL or SQLite
+  (Tortoise ORM + aerich migrations), AES-256-GCM private-key encryption, and
+  a complete REST API. The pure PKI domain logic lives in `packages/kca-core`;
+  the deployable app is `packages/kca-app`.
 - **`web/`** — Rust + [Sycamore](https://sycamore.dev) compiled to WebAssembly
   by [Trunk](https://trunkrs.dev), styled with Bootstrap 5.3 (vendored under
   `web/vendor/`) and a dark PKI-console theme.
@@ -50,6 +50,45 @@ OIDC_0_REDIRECT_URI=https://kca.example.com/auth/default/callback
 
 `server/.env.example` documents every setting.
 
+## Database backends
+
+PostgreSQL is the default production backend. KCA also supports persistent,
+file-backed SQLite for single-writer deployments. Configure it from `server/`
+with either the component settings:
+
+```sh
+export DATABASE_ENGINE=sqlite
+export DATABASE_NAME=/data/kca.db
+export DATABASE_OPTIONS=busy_timeout=5000
+```
+
+or one URL:
+
+```sh
+export DATABASE_URL='sqlite:///data/kca.db?busy_timeout=5000'
+```
+
+Run migrations before starting or upgrading the app:
+
+```sh
+uv run aerich upgrade
+```
+
+Tortoise enables WAL journaling and foreign-key enforcement by default; the
+busy timeout allows concurrent readers and a writer to wait briefly for locks.
+Only in-memory SQLite test databases create their schemas implicitly.
+
+For containers, mount a persistent volume at `/data` for both the migration
+and application containers and use the same SQLite URL for each. The image's
+`/data` directory is writable by its non-root application user. When invoking
+`aerich upgrade` directly in the image, set its working directory to `/app`
+(for example, `docker run -w /app ...`). Keep SQLite to one application
+writer/replica, and use SQLite-aware backups rather than independently copying
+live database, WAL and shared-memory files.
+
+When changing models, migration SQL must support both PostgreSQL and SQLite.
+The PostgreSQL migration commands below remain the default development flow.
+
 ## What it does
 
 ### Vaults