CouchDB: the one step that is left to your hand
The wizard names this step and does not guess at it — the databases to create, the security document each one needs, and the setting that cannot be changed later.
Saphan keeps law and evidence in CouchDB. The first-run wizard tests the address you give it and writes the credentials, and then it names one step and stops: creating the databases is not automated.
That is deliberate, and it is worth understanding before you do it by hand. The database names, the roles that may write to each, and one storage setting that cannot be changed after the databases exist are decisions about your deployment. A wizard that guessed at them would be guessing at something irreversible.
The installer is resumable. Do this step, then run the same command again and it continues from where it stopped.
1 · The system databases
The CouchDB image does not create them. Until they exist, authentication and the change feed behave in ways that are easy to misread as bugs — so this is the first thing to do, not a detail. With your admin credentials:
2 · Four databases, one per class of thing Saphan stores
The four classes differ in how they change and in whether they can be rebuilt, and that is what decides your backup duty:
| class | changes by | rebuildable? |
|---|---|---|
| law | a ratification act | yes — it can be dropped and rebuilt from the repository |
| working material | supersession | no — the database is the only copy |
| record | append only | no — the database is the only copy |
| telemetry | append only | no — the database is the only copy |
⚠ Three of the four are the only copy of what they hold. Whatever backup you run, it has to cover those three.
The names are yours to choose. Create one database per class:
3 · A security document per database
Each database needs a _security document restricting who may write to it. The shape is the
same; the role differs by class:
| database | who writes | shape |
|---|---|---|
| law | the ratification act alone | single writer, world read-only |
| working material, record | the engine's own act | engine-written |
| telemetry | the capture path only | capture-only |
⚠ The role names are yours, and they must match the credentials the engine and the capture path actually authenticate with. A role named here that nothing authenticates as is a database nothing can write to.
4 · The setting you cannot change afterwards
CouchDB's shard and replica counts — q and n — are fixed when a database is created and
cannot be changed later. Changing your mind means creating new databases and copying the data
across. Decide them before step 2, not after.
When it is done
Run the setup command again; it continues from where it stopped, and Verifying an install is how you check what you have.
First run: setting the machine up at /setup
A machine with no owner is set up in a browser, and that is the only surface that can do it: the window, the six screens, and the ceremony that does not repeat.
Air-gapped installation (Enterprise)
A signed package, installed system-wide on a host with no network path to anything — what it puts on the machine, and what still needs your hand afterwards.