Improve the history archive docs - #2852
Open
jayz22 wants to merge 1 commit into
Open
Conversation
Contributor
There was a problem hiding this comment.
Pull request overview
Reorganizes validator archive guidance around installation, operation, verification, repair, and mirroring.
Changes:
- Defines Full Validators as publishing complete history.
- Adds archivist command-selection and operational guidance.
- Separates optional content verification from routine examples.
Reviewed changes
Copilot reviewed 2 out of 2 changed files in this pull request and generated 2 comments.
| File | Description |
|---|---|
docs/validators/README.mdx |
Clarifies Full Validator archive completeness. |
docs/validators/admin-guide/publishing-history-archives.mdx |
Reworks archivist workflows and examples. |
💡 Configure MCP servers for context-aware, tailored reviews. Learn more in the docs.
jayz22
force-pushed
the
docs/archivist-updates
branch
from
September 12, 2026 00:09
6cae4d0 to
ab58426
Compare
leighmcculloch
approved these changes
Sep 12, 2026
Rework the archivist docs around what an operator is actually trying to do — install the tool, decide where to run it, pick a command, then scan / repair / mirror: - Drop --verify from the default examples and give it its own section covering what it checks and what it costs. - Add a command-selection table, and document --low/--high. - Note that stellar-archivist is separate from stellar-core: run it off the validator host, and never stop the validator to work on its archive. - Remove the stray `systemctl start stellar-core` at the end of the section, which paired with nothing and implied Core had been stopped. - Fix an invalid ':::attention' admonition and copyedit throughout. Also establish that a Full Validator's archive is a complete one. Neither the Full Validator definition nor the Tier 1 requirements mentioned archive depth, so nothing said an archive should reach back to the first ledger. Tier 1 delegates its archive requirement to the Full Validator definition, so stating completeness there covers both. The archives page now frames publishing as two stages, so the Backfilling section no longer implies you are finished when the archive holds only recent checkpoints.
jayz22
force-pushed
the
docs/archivist-updates
branch
from
September 12, 2026 00:25
ab58426 to
61d8b65
Compare
Contributor
There was a problem hiding this comment.
Pull request overview
Copilot reviewed 3 out of 3 changed files in this pull request and generated 2 comments.
Suppressed comments (1)
docs/validators/admin-guide/publishing-history-archives.mdx:245
- This advice is ambiguous for
mirror:mirror --verifyvalidates only files downloaded from the source and skips existing destination files unless--overwriteis also set, so it does not generally find corruption in an existing archive. Direct operators toscan --verifyandrepair --verifyfor that workflow.
Leave it off for routine completeness checks and for fixing missing files. Turn it on to find and fix corruption, where a file exists but its contents are wrong.
| | Fix missing or corrupt files in an archive you already have | [`repair`](#repairing-an-archive) | | ||
| | Build an archive from scratch, or backfill a range of history | [`mirror`](#mirroring-an-archive) | | ||
|
|
||
| All three accept `--low` and `--high` to restrict the work to a ledger range; both bounds are rounded outward to the nearest checkpoint. |
|
|
||
| ### Where to run stellar-archivist | ||
|
|
||
| stellar-archivist is a standalone tool. It does not link against or communicate with `stellar-core`; all it needs is read and write access to the archive itself. That access can be a local filesystem path (`file://`), an HTTP(S) source, or a cloud object store (`s3://`, `gcs://`, `azblob://`, `b2://`), so you can run it from any machine that can reach your archive. |
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.
Reworks the stellar-archivist docs to make it easier to follow by new validators.
--verifyis dropped from the default examples--low/--highsystemctl start stellar-coreat the end of the section, which implied Core had been stopped.Also defines a Full Validator as publishing a complete archive.