Skip to content

docs(selfhost): .env.selfhost.example never mentions ledger anchoring, the one feature self-host uniquely can run #9848

Description

@JSONbored

Problem

.env.selfhost.example documents provider selection, telemetry, and the rest of the self-host surface, but
says nothing about LOOPOVER_LEDGER_ANCHOR_*. Anchoring is the one capability a self-host deployment
uniquely can run — the hosted deployment retired review execution, so its decision_ledger is empty and
there is nothing there to anchor — and the sample file an operator actually copies never mentions it.

The variables are documented in self-hosting-configuration.mdx, but nobody reads a docs table to discover
a feature they don't know exists.

What this cost, concretely

Provisioning anchoring on a live instance (1,626 ledger rows) surfaced three separate stumbling blocks that
the sample file is the natural place to prevent:

  1. All-or-nothing. Setting one half makes anchoring silently never run. Preflight flags it, but only if
    you already knew to set anything.
  2. The PEM must be single-line with \n escapes. A real multi-line value breaks Docker's env_file
    parsing. (pemToBytes handles the escapes; nothing says so where an operator would look.)
  3. The Rekor shard rotates annually and the built-in default can only ever lag. When it does, anchors
    record status: failed and the operator has no pointer toward the override that fixes it (orb(anchor): the default Rekor shard was never deployed, and the failure it causes does not name the URL #9844).

Fix

A section in .env.selfhost.example covering: what anchoring buys over the plain hash chain, that it is
self-host territory and the ledger is per-instance, npm run ledger:anchor-keygen, the all-or-nothing
constraint, the \n-escape requirement, the shard override with the live value, and the git backend.

Deliverable

  • Section added; docker-compose-env-example-parity and selfhost:config-lint still pass.

Metadata

Metadata

Assignees

Labels

maintainer-onlyOwner-only work — yields no Gittensor points.

Projects

No projects

Milestone

No milestone

Relationships

None yet

Development

No branches or pull requests

Issue actions