docs: a bootstrap page for dolos bootstrap stelae - #1217
Open
scarmuega wants to merge 1 commit into
Open
Conversation
`docs/content/bootstrap/` had a page per bootstrap method — mithril, snapshot, relay, local — and none for stelae, which has shipped since `dolos-stelae-restore`. Everything an operator needed was in ADR-004, a design record addressed to implementers, and in `--help`. Adds `docs/content/bootstrap/stelae.mdx` in the shape the sibling pages have, and its LinkCard in the index grid. Covers the two `--source` spellings, `--point`, `--continue` as the resume, `sync.max_history` as the bound on what gets fetched, `[stelae.registry]` by link to the schema page, `--insecure`'s loopback-only scope, and `--scratch-dir`. Prose only: no new command surface, no new flag, no behavior change. Every flag and default is read off `dolos bootstrap stelae --help` as built from main. Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
|
No actionable comments were generated in the recent review. 🎉 ℹ️ Recent review info⚙️ Run configurationConfiguration used: defaults Review profile: CHILL Plan: Pro Plus Run ID: 📒 Files selected for processing (2)
Included review availability: Your plan includes up to 2 reviews per rolling hour; 0 remain after this review. 📝 WalkthroughWalkthroughThe PR adds a ChangesStele bootstrap documentation
Estimated code review effort: 2 (Simple) | ~10 minutes Merge Risk: ⚪ Minimal · up to This documentation-only change adds guidance for an existing bootstrap command without changing product behavior; no actionable merge-blocking risk remains. Possibly related PRs
🚥 Pre-merge checks | ✅ 5✅ Passed checks (5 passed)
✨ Finishing Touches 💡 1🛠️ Fix failing CI checks 💡
🧪 Generate unit tests (beta)
Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out. Comment |
There was a problem hiding this comment.
Pull request overview
Adds operator documentation for bootstrapping Dolos from local or OCI-hosted steles.
Changes:
- Documents sources, restore flags, resumption, history filtering, credentials, and progress output.
- Adds Stele to the bootstrap method grid.
Reviewed changes
Copilot reviewed 2 out of 2 changed files in this pull request and generated 3 comments.
| File | Description |
|---|---|
docs/content/bootstrap/stelae.mdx |
Adds the Stele bootstrap guide. |
docs/content/bootstrap/index.mdx |
Links to the new guide. |
Suppressed comments (3)
docs/content/bootstrap/stelae.mdx:119
- A stele need not contain every epoch the publisher has:
snapshot publish --epochscan restrict the exported windows, and the restore format also accepts a ledger-only stele with no epoch layers.sync.max_historyfilters the history actually included in the artifact, so this universal claim is inaccurate.
A stele carries every epoch the publisher had. This node does not necessarily
want them all, and `sync.max_history` is what decides: it is a window in slots
measured back from the snapshot's tip, and epochs whose layers fall entirely
below that floor are dropped from the restore plan — so they are never fetched at
all, not fetched and then pruned.
docs/content/bootstrap/stelae.mdx:154
- This labels the sequence as the epoch entered by the cursor, but the exporter computes it as
epoch_of(cursor) + 1and uses it as the immutable tag number. Mid-epoch publications are supported, so the cursor has not necessarily just entered that sequence. Label this as the publication sequence/tag number instead.
sequence: <the epoch that cursor has just entered>
docs/content/bootstrap/stelae.mdx:169
- Neither the epoch-boundary nor the “up to a few days” guarantee holds for every accepted source.
dolos snapshot publishsupports mid-epoch cursors, and a user can restore an arbitrarily old pinnedepoch-N, requiring many epochs of catch-up. Describe synchronization relative to the recorded cursor, and limit the short catch-up claim to a recent boundary-aligned publication.
Steles are cut at epoch boundaries, so a restored node is at the end of an epoch
and not at the chain tip. Starting `dolos daemon` afterwards chain-syncs the
remaining partial epoch from your configured upstream peer — up to a few days of
blocks on mainnet.
💡 Add a code-review agent skill or configure MCP servers for context-aware, tailored reviews. Learn more in the docs.
Comment on lines
+65
to
+68
| A repository holds more than one stele. `--point latest` reads the most recent | ||
| one published; `--point epoch-N` reads the stele published at the end of epoch | ||
| `N`, which is how you pin a restore to a known boundary rather than to whatever | ||
| the publisher pushed most recently. |
Comment on lines
+82
to
+86
| `--continue` already meant "go ahead even though there is data here, the | ||
| subcommand knows how to resume". For a stele restore that is literally true — it | ||
| is what makes the run consult the progress file an interrupted attempt left in | ||
| the storage directory, so the layers that attempt already committed are neither | ||
| fetched again nor written again. |
Comment on lines
+88
to
+97
| A run **without** `--continue` starts over, and it starts over properly: a | ||
| progress file it did not ask to honour is overwritten rather than obeyed. That is | ||
| deliberate. A progress file that outlived the stores it described would otherwise | ||
| skip layers onto nothing, leaving a node that looks restored and is not. | ||
|
|
||
| <Aside type="caution"> | ||
| Interrupting a restore is safe, but only `--continue` picks up where it left off. | ||
| Re-running the same command without it discards the interrupted attempt's | ||
| progress and starts from the beginning. | ||
| </Aside> |
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Plan:
plans/dolos-stelae-bootstrap-docs.md(Brain/txpipe)What changed
docs/content/bootstrap/stelae.mdx(new) — a bootstrap page fordolos bootstrap stelae, in the shape the four sibling pages already have.docs/content/bootstrap/index.mdx— itsLinkCardin the method grid.Prose only: no new command surface, no new flag, no behavior change.
The page covers the six things the plan named, because each is a thing an
operator gets wrong without it:
--sourcein both spellings (file://DIR,oci://HOST/PATH)--point:latestorepoch-N, and that a repository holds both--point--continueis the resume; a run without it starts over properly--continueis the resumesync.max_historybounds what is fetched[stelae.registry], by link rather than restatement--insecureis loopback / in-cluster only--insecure--scratch-diris documented too — it is the fourth flag in the subcommand's--helpand an operator staging a mainnet transfer needs it.Done criterion 2 — every claim read off the binary
cargo build --bin dolosat07d28245(main), then:Claims that are not in
--helpare read off the source rather than off a plan:--point/--insecure/--scratch-dirare ignored for afile://source rather than being an error" —
run()insrc/bin/dolos/bootstrap/stelae.rsdispatches
Source::Dirtorestore_dir, which takes none of them.file://./steleandfile://steleare relative;file:///absis absolute" —a_file_source_names_a_directoryin the same module.https://URL, or anoci://URL that names a tagare rejected at the command line" —
an_unusable_source_is_refused.sync.max_historyfloor are never fetched at all" —retain_history/planincrates/snapshot/src/restore.rs; unsetmax_historyreturns every epoch.
report()in the same module,including that
epochs:namessync.max_historyonly whenskipped_epochs > 0and
resumed:prints only whenoutlook.inherited > 0.adrs/004_stelae_snapshots.md, Consequences.Done criterion 3 — the docs site builds
Not verifiable in this repository, and reported rather than claimed.
docs/here is content only: no
package.json, noastro.config.*, and no docs job in.github/workflows/. The site is built elsewhere from this content.What was verified instead: the new page carries the same frontmatter keys as its
siblings (
title,sidebar.label,sidebar.order), imports onlyAsidefrom@astrojs/starlight/componentsand uses only that component, and itscross-document links follow the relative form already used across the tree
(
../bootstrap,../configuration/schema#sync-section,../configuration/schema#stelaeregistry-section). A reviewer with the sitecheckout should confirm the build and the two schema anchors resolve.
Judgment calls a reviewer should rule on
relay. The plan says the method mattersmore than the others do — but it also says which method a release recommends
is a product decision nobody has recorded, so the page does not take it by
ordering. Move it up if that decision has since been made.
oci://registry.example.com/dolos-snapshots/mainnet, a shape rather than anendpoint, because the official one is not provisioned yet
(
dolos-stelae-cloudflare-registry). Worth a follow-up edit once it exists.Out of scope by the plan's own scope decisions and untouched:
dolos snapshot publishdocs, ADR-004, and the legacybootstrap snapshotpage.🤖 Generated with Claude Code
Summary by CodeRabbit