Uh oh!
There was an error while loading. Please reload this page.
Docs/content refresh - #490
Open
JasonVranek wants to merge 21 commits into
Open
Conversation
Brings over the docs/docs tree, sidebars.js and api/signer-api.yml from d628b78 (PR #472 head) as a straight file replacement. The docs on main have not changed since that PR's merge base, so this is a clean port. New pages: - get_started/mux-key-loaders.md - get_started/running/k8s.md - get_started/running/metrics-catalog.md - developing/extending-pbs.md - developing/commit-modules.md (replaces developing/commit-module.md) Removed: developing/custom-modules.md (folded into commit-modules.md). sidebars.js rides along because it is what wires the new pages in, and it also adds developing/prop-commit-signing.md, which was an orphan on main. Out of scope here (later PR): docs/versioned_docs, docs/versions.json, the docusaurus.config.js versioning keys, docs/src/pages/index.js and crates/common/src/config/module.rs.
main and PR #472 both touched this file, so it is merged by hand rather than replaced. Kept from main: the [[relays]] get_header stream block, the fuller Stader loader wording, and the fulu_fork_slot example. Taken from the PR: the module -> service terminology rename, the "All fields are required" note on the inline custom chain, and the #signer-service docs anchor. Also corrected against the v0.10.0 code while merging: - [signer.tls_mode] claimed a default of "certificate" with self-signed auto-generation. default_tls_mode() returns Insecure, and the cert path is read with std::fs::read (crates/common/src/config/signer.rs), so the files must already exist. - [signer.remote] is listed as a supported signer type but StartSignerConfig bails with "Remote signer configured" at startup. Marked NOT IMPLEMENTED and dropped from the supported list, matching configuration.md ("for now, one remote signer is supported: Dirk"). - [[signer.dirk.hosts]] used `accounts`; DirkHostConfig calls the field `wallets`.
Findings from an audit of the ported pages against tag v0.10.0.
running/docker.md
- The generated compose file is `cb.docker-compose.yml`, not
`.cb.docker-compose.yml`; only the env file has a leading dot
(crates/cli/src/docker_init.rs: CB_COMPOSE_FILE vs CB_ENV_FILE).
- Bumped the six pinned `ghcr.io/commit-boost/commit-boost:v0.9.6`
image tags to v0.10.0.
developing/extending-pbs.md
- The entry-point snippet used an unbound `config_path`. Bound it to
`PathBuf::new()` to match examples/status_api/src/main.rs, and added
a note that PbsService::run only starts the config-file watcher when
that path is non-empty (crates/pbs/src/service.rs), so the example as
written does not hot-reload.
- The same caveat is now cross-linked from the auto-reload sections of
configuration.md and running/docker.md, which claimed auto-reload
unconditionally.
get_started/mux-key-loaders.md
- Dropped the "first-match semantics / checked in order" paragraph. All
mux pubkeys are flattened into a single lookup map, and a pubkey in
two muxes is a hard startup error ("duplicate validator pubkey in
muxes", crates/common/src/config/mux.rs) rather than a first-wins
fallback. Config order is irrelevant.
- `default_pbs.http_timeout_seconds` is an internal field name; the
user-facing key is `http_timeout_seconds` under `[pbs]`.
running/binary.md
- CB_CHAIN_SPEC overrides the `path` of the top-level `chain` key (not
a `[chain]` section), and only for the { genesis_time_secs, path }
form. It is silently ignored for a network name or the fully inline
custom object (crates/common/src/config/mod.rs from_env_path).
get_started/configuration.md
- The minimal examples used `url = ""` for a relay. RelayEntry
deserializes the url with Url::deserialize and parses the userinfo as
a BLS pubkey, so an empty string never starts. Replaced with a
parseable placeholder plus a warning.
- Noted that the inline custom-chain object has no optional fields.
get_started/building.md
- Refreshed the stale sample log output: version 0.7.0 / 0.8.0-rc.1,
and the `events_subs` field that no longer exists in the PBS startup
log. Regenerated from the actual log statements in
crates/pbs/src/service.rs, crates/pbs/src/routes/router.rs and
crates/signer/src/service.rs, including the fields the signer now
logs and the TLS warning the sample config actually produces.
get_started/overview.md
- `.releases/v0.10.0-rc1.yml` no longer describes the current release;
pointed at `.releases/v0.10.0.yml` and its commit.Two things the ported content did not cover.
troubleshooting.md
The "PBS" section at the end still carried pre-0.8 log output: a
`Starting PBS service address=... events_subs=0` startup line (the
`events_subs` field no longer exists) and `status{req_id=...}:` style
spans. The request span is now created by tracing_middleware with an
empty name and carries `method` and `req_id` plus the per-route fields
recorded by each handler, so every line renders as `INFO : <message>
<event fields> <span fields>`. Regenerated all four samples from the
handlers in crates/pbs/src/routes/, added the TraceLayer "Responded
with" line, and documented the 204/202 outcomes the handlers return.
running/k8s.md
The values table correctly reports `image.tag` defaulting to v0.4.0,
which really is what provisioning/k8s/commit-boost/values.yaml pins.
That image predates the unified `commit-boost pbs` CLI the same chart
invokes via `command`/`args`, so installing the chart unmodified cannot
work. Added a warning to set the tag explicitly.Signer Module -> Service heading consistency, correct a copy-pasted image alt, disambiguate the three 'Overview' page titles, PBS capitalization, normalize configuration anchor links, code-format a config value, and give the troubleshooting healthy-logs block its own heading.
Wire building.md into the sidebar (it was orphaned), fix its dead `git checkout stable` (stable is retired) to the release-commit pattern, and replace the duplicated build steps in the getting-started overview with a pointer, so there is one build guide instead of two diverging copies.
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 freeto join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
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.
Update docs for parity with
v0.10.0, depends on #488