# Deploying & scaling Rindle

Rindle's one topology, from the colocated pair to a read-scaled fleet: an HCTree write-master, read-only followers, canonical backup, concurrent writes, and follower-affinity placement.

A synced Rindle app has one deployment topology: a `rindle-replicator` **HCTree
write-master** feeding one or more `rindled` **read-followers**. The [API
server](/docs/api-server) sends writes to the master and reads to the follower fleet;
browsers subscribe to the followers. Self-hosting can put the master and one follower on
one box; Rindle Cloud starts them on separate machines so scaling to more followers is an
in-place count/placement change —
the schema, queries, mutators, and [correctness
contract](/docs/architecture#the-correctness-contract) do not change.

Run the built profiles yourself under a [self-host license](/pricing#self-host), or let
[Rindle Cloud](https://cloud.rindle.sh) provision and operate the same components. The
former standalone write-accepting daemon, Postgres relay/source path, and standalone read
router are retired.

## The deployment rungs

### 1 · Colocated pair

The smallest deployment is **one machine, two processes**. The HCTree master owns the
authoritative database and journal; one `rindled` follower tails it over loopback and owns
the live query pipelines. Both database files share one volume. The API server still uses
two URLs — writes to the master, reads to the follower — so moving up a rung is an
infrastructure change, not an app rewrite.

With a backup block, the colocated shape adds continuous logical-journal and portable-base
shipping to object storage. Because both engines are CPU-bound, a colocated box should
have at least **2 vCPU**. It remains useful for local development and self-hosted small
workloads; new Rindle Cloud apps use the separate replicated shape below.

### 2 · Replicated

The same master and one follower run on **separate machines**, optionally in different regions. Read CPU and
storage no longer contend with write execution, and either role can restart independently.
A fresh follower restores from the canonical object-store generation, then catches up and
tails the master's private fan-out.

### 3 · Read-scaled

One master feeds **N followers**, optionally distributed across regions. Reads, live
subscriptions, and distinct materializations scale horizontally with the followers. Writes
continue to enter through the singleton master so every follower observes one commit order.

The browser and API server use one stable fleet host. A signed **follower-affinity ticket**
places the browser WebSocket and its HTTP lease/read requests on the same nearby follower.
If that follower disappears, the client clears the ticket and the edge places it on a live
sibling. The old read-router model — returning a different `wsEndpoint` with each lease — is
gone; placement stays at the edge and the public host does not change.

For local parity, `rindle up` always renders and supervises the native `rindle-dev-edge`, including for a
fleet of one. Launch app processes through `rindle exec -- …`; it derives the stable fleet-edge
read/ws binding and write-master binding from `rindle.ncl`, so scaling followers changes no app
configuration.

## Writes: one order, concurrent ingress

"One write-master" no longer means "one transaction at a time." The master pools HCTree
`BEGIN CONCURRENT` connections. Disjoint transaction bodies can execute in parallel; HCTree
validation assigns each successful commit the `cid` that defines the one journal order.

- `RINDLE_WRITE_CONNECTIONS` controls concurrent-open-session capacity (default `8`).
- `RINDLE_WRITE_THREADS` controls execution parallelism (default `1`); raise it toward the
  cores available to the master.
- Replayable pure-write OCC conflicts retry inside the master. A read-bearing conflict
  re-drives the authoritative mutator generator, because replaying only its SQL would be
  unsound.
- A migration briefly quiesces write admission and applies one ordered DDL transaction.

This scales write execution vertically while retaining one sequencing point. Followers add
read capacity; adding another master is a database-sharding decision.

## Durability and recovery

With a `backup` block, the master ships logical journal segments and portable bases to an
S3-compatible store. The durable manifest watermark bounds local journal GC. Hosted backup
maintenance repacks segments, produces new bases, plans retention, and scans for orphans;
off-host `rindle backup drill` jobs restore and verify the same generation on a schedule.

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
whose cursor is older than retained history must restore rather than request an unbounded
replay.

## What is available

| Shape | Self-hosted data plane | Rindle Cloud |
| --- | --- | --- |
| **Colocated pair** | ✅ built | Legacy apps only; not offered for new creates |
| **Replicated** | ✅ built | ✅ provision and connect today |
| **Read-scaled** | ✅ built, including affinity placement | ✅ provision and connect today |
| **Postgres-sourced** | ⛔ retired pending a replacement ingestion design | ⛔ unavailable |

Every supported Rindle Cloud app exposes a browser fleet WebSocket, a bearer-gated
follower read/control endpoint, and a separately bearer-gated write-master endpoint. The
dashboard's Connect panel supplies all three plus their server-side tokens; see [Connect
your app](/docs/cloud-connect).

## Run it yourself, or have us run it

- **Self-host** — operate the master, followers, backup generation, and restore drills in
  your cloud under one flat company license independent of machine count and CPU size.
- **Rindle Cloud** — the control plane converges the same components for you, monitors their
  desired and observed state, and exposes resize, suspend/reactivate, logs, and metrics.

## Next steps

- [Cloud quickstart](/docs/cloud-quickstart) — provision a managed app.
- [Connect your app](/docs/cloud-connect) — wire the split server client and affinity-aware
  browser client.
- [The three-tier architecture](/docs/architecture) — the application shape around the data
  tier.
- [Run the daemon](/docs/daemon) — the read-only `rindled` follower in full.
- [Is Rindle for you?](/docs/compare) — where a single ordering point fits.

---

[View this page on Rindle](https://rindle.sh/docs/deploy)