Deploying & scaling Rindle

Rindle has two explicit data-tier profiles. Standalone is one rindled, one wal2 SQLite file, and one serialized write authority serving the complete synced-app surface. Replicated is one concurrent HCTree write master with zero or more read-only rindled followers. Every successful write receives one total order in either profile.

Applications see one edge, not those individual processes:

RINDLE_URL=https://app.example.com
RINDLE_DATABASE_TOKEN=<server-only-bearer>

Standalone can expose that one origin directly. A fleet edge routes SQL and migrations to the master and follower protocols to the selected read replica. A query lease tells the browser which public WebSocket endpoint and follower-affinity ticket to use. The ticket controls placement, not authorization.

# Deployment shapes

# Standalone desktop or hosted micro

Set profile = "standalone" in rindle.ncl, or run the thin container with ROLE=standalone. One source-less rindled serves authoritative SQL, mutations, migrations, reads, materializations, and subscriptions from the same file and origin. It is a good fit for a desktop/local app or a deliberately single-node hosted micro app whose recovery contract is provider volume snapshots.

Standalone has no follower fan-out, HCTree/OCC writer pool, continuous journal backup, PITR, or automatic failover. Writes serialize. It does not scale out by adding a second writable daemon. Moving to a fleet is an export/import into a new HCTree store followed by a routing cutover; the wal2 file is not promoted in place.

# Master-only SQL

The smallest durable shape is one rindle-replicator. Its HCTree database is the authoritative state and it serves the public SQL surface, interactive transactions, ordered migrations, and backup shipping. Use it with @rindle/sql-client, Drizzle, or rindle sql when live queries are not required.

# Master plus one follower

Add one rindled follower for the complete synced-app stack. The follower restores from the master’s lineage, tails its journal into a WAL2 SQLite database, and owns materialized queries and live subscriptions. The pair can share a host for local or small deployments. They remain separate processes.

# Read-scaled fleet

One master can feed multiple followers. Reads, distinct materializations, and subscriptions scale across them while all writes retain the same sequencing point. A stable edge and signed affinity tickets keep each browser’s lease and WebSocket on one follower and re-place it after a failure.

This multi-follower shape is built for self-hosting. It is not currently a Rindle Cloud SKU.

# Writes: one order, topology-specific execution

Standalone deliberately has one serialized wal2 writer. Its commit’s captured changes cross the local IVM worker barrier and become visible without a replication wait. wal2 lets reader snapshots sit beside that writer, so a read-only public SQL transaction never parks writes: each one is backed by its own reader snapshot. A held snapshot pins wal2 checkpointing, so open read-only transactions are capped — RINDLE_READ_TXN_SESSIONS (default 4); past the cap a begin answers 503 instead of queueing.

In the replicated profile, “one write master” does not mean “one transaction at a time.” The master pools HCTree BEGIN CONCURRENT connections. Disjoint transaction bodies can execute in parallel. HCTree validation assigns successful commits the cid that defines the journal order.

• RINDLE_WRITE_CONNECTIONS controls open transaction capacity (default 8).
• RINDLE_WRITE_THREADS controls execution parallelism (default 1). Raise it toward the cores available to the master.
• Replayable pure-write conflicts retry inside the master.
• A read-bearing conflict re-drives the authoritative mutator, because replaying only its generated SQL is unsound.

Followers scale reads. Adding another write master is an application-level sharding decision, not a replica-count change.

# Local lifecycle

rindle dev owns the normal development lifecycle in one command:

rindle dev --migrate --gen shared/schema.gen.ts -- \
  vite dev --port 3000

It:

1. evaluates rindle.ncl once
2. starts one standalone daemon, or the replicated master, followers, and rindle-dev-edge
3. waits for readiness
4. applies and watches migrations
5. generates and watches schema
6. injects RINDLE_URL plus RINDLE_DATABASE_TOKEN
7. forwards signals
8. stops the fleet with the app command

When you need to supervise only the data fleet, use rindle up. rindle exec -- … remains as a compatibility adapter that runs one command with bindings derived from rindle.ncl. For new projects, use rindle dev.

The replicated profile runs the native development edge even for one follower, so local code exercises the same unified ingress and affinity path as production. The standalone profile binds read HTTP, write HTTP, and subscriptions directly to its one daemon.

# Durability and recovery

Standalone desktop/local recovery is an app-owned SQLite snapshot (VACUUM INTO, the backup API, or an OS backup) on an explicit schedule. Hosted micro recovery is a completed provider volume snapshot restored onto a replacement volume and daemon. Its RPO is the configured snapshot interval; its RTO includes provisioning and restore downtime. Compute may scale to zero, but the persistent volume and snapshots do not.

A product-initiated standalone snapshot must quiesce/close the writer. Before promising scheduled snapshots on a provider, qualify an active-wal2 snapshot → new-volume restore, run SQLite integrity checks, and prove the fresh-query correctness contract. Do not describe this as continuous backup or HA.

In a fleet, a backup block makes the master ship logical journal segments and portable bases to an S3-compatible store. The durable manifest watermark bounds local journal garbage collection. Maintenance compacts segments, creates new bases, enforces retention, and scans for orphans. Off-master rindle backup drill jobs prove the same generation can be restored.

A new follower restores a WAL2 database from the latest portable base and replays the tail. A replacement master restores and promotes an HCTree leader from the same lineage. A follower older than retained history restores instead of requesting an unbounded replay.

# Rindle Cloud on OVH

Rindle Cloud’s Cloudflare-hosted control plane records billing, placement, DNS, and versioned intent. It commits desired state to the fleet repository. rindle-poold converges packed processes on the assigned OVH box and reports the applied generation. Cloudflare Tunnel publishes the stable app-<id>.rindle.cloud ingress.

The hosted menu is deliberately fixed:

• SQL, $5/month — master only.
• Sync, $10/month — the same master plus one follower on the same fleet box.

Each serving process gets a 5 GB database, 1 CPU, and 512 MB of memory. Streaming backup is included. The dashboard does not currently expose host, region, machine-size, volume-size, or follower-count controls.

# What is available

# Run it yourself, or have us run it

• Self-host — run standalone with your snapshot/restore contract, or operate the fleet master, followers, edge, backup lineage, and restore drills in infrastructure you control.
• Rindle Cloud — use the fixed SQL or Sync plan on Rindle’s packed OVH fleet and let the control plane converge it for you.

Both use the same schema, SQL client, API server, browser client, migration files, and correctness contract.

# Next steps

• Cloud quickstart — provision SQL or Sync.
• Connect your app — use one URL and one token.
• The three-tier architecture — the application shape around the data tier.
• Run the daemon — standalone authority and follower postures in full.