docs(book): fix six instructions that fail or misinform#10956
Open
CodeMongerrr wants to merge 3 commits into
Open
docs(book): fix six instructions that fail or misinform#10956CodeMongerrr wants to merge 3 commits into
CodeMongerrr wants to merge 3 commits into
Conversation
Each fix verified against the codebase at main: - supported-platforms: document the real MSRV split (1.88 workspace, 1.91 zebrad) instead of the incorrect 1.89 - install: stop documenting a build for the tor feature that cannot build (commented out in zebra-network/Cargo.toml); say it's disabled, matching troubleshooting.md - docker: 'docker build' has no --env-file flag; use the --build-arg FEATURES form the page itself shows further down - mining-docker: bare MINER_ADDRESS does nothing on a zebrad container; use ZEBRA_MINING__MINER_ADDRESS, fix the t3/P2SH address described as t1/P2PKH, and point at the ready-made docker/mining compose stack - metrics: prebuilt binaries already ship prometheus (no rebuild), and the config moved to docker/observability/prometheus/prometheus.yaml - profiling: no [profile.profiling] exists in any manifest; use the release profile Addresses ZcashFoundation#10947
Contributor
There was a problem hiding this comment.
Pull request overview
Updates six Zebra Book pages to correct inaccurate build, Docker, mining, metrics, MSRV, and profiling instructions tracked by #10947.
Changes:
- Corrects Rust-version and feature availability documentation.
- Fixes Docker and mining configuration examples.
- Updates metrics and profiling commands.
One metrics command still uses a Compose-specific Prometheus target without defining its hostname.
Reviewed changes
Copilot reviewed 6 out of 6 changed files in this pull request and generated 1 comment.
Show a summary per file
| File | Description |
|---|---|
book/src/user/supported-platforms.md |
Documents the MSRV split. |
book/src/user/mining-docker.md |
Fixes mining environment variables and address details. |
book/src/user/metrics.md |
Updates feature and Prometheus configuration guidance. |
book/src/user/install.md |
Documents disabled Tor support. |
book/src/user/docker.md |
Corrects custom-image build arguments. |
book/src/dev/profiling-and-benchmarking.md |
Uses the existing release profile. |
|
|
||
| # run prometheus with the included config | ||
| sudo docker run --detach --network host --volume prometheus-storage:/prometheus --volume /path/to/zebra/prometheus.yaml:/etc/prometheus/prometheus.yml prom/prometheus | ||
| sudo docker run --detach --network host --volume prometheus-storage:/prometheus --volume /path/to/zebra/docker/observability/prometheus/prometheus.yaml:/etc/prometheus/prometheus.yml prom/prometheus |
Contributor
Author
There was a problem hiding this comment.
Good catch, thanks. That config is written for the compose stack, so its scrape target is the zebra service name and a host-networked container would scrape nothing. I replaced that step with a minimal localhost config written inline, and added a note pointing anyone who'd rather skip the manual setup at docker-compose.observability.yml. Fixed in 1dd5281.
9 tasks
The observability-stack config scrapes Compose service names (zebra:9999), which don't resolve in the host-networked container this guide runs, so Prometheus would silently scrape nothing. Inline a minimal localhost config for the manual flow and point readers at the docker-compose observability stack as the one-command alternative.
conradoplg
requested changes
Jul 24, 2026
conradoplg
left a comment
conradoplg
left a comment
Collaborator
There was a problem hiding this comment.
Thanks! Just needs one adjustment
Comment on lines
+11
to
+12
| cargo build --release | ||
| sudo samply record ./target/release/zebrad |
Collaborator
There was a problem hiding this comment.
Suggested change
| cargo build --release | |
| sudo samply record ./target/release/zebrad | |
| cargo build --profile profiling | |
| sudo samply record ./target/profiling/zebrad |
Collaborator
There was a problem hiding this comment.
This does work (it is defined in .cargo/config.toml so please revert this
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.
Motivation
Closes #10947. Six places in the Zebra book give instructions that either fail outright or misinform the reader, per the 2026-07-14 audit in that issue. I re-verified each one against
mainbefore changing anything.Solution
supported-platforms.md— document the real MSRV split: 1.88 for the workspace/library crates (Cargo.toml), 1.91 for thezebradbinary (zebrad/Cargo.toml); the page previously said 1.89, which matches neitherinstall.md— stop documenting a build of thetorfeature that cannot build (it's commented out inzebra-network/Cargo.toml); the section now says Tor support is disabled, matchingtroubleshooting.mdand linking the same tracking comment (Restore arti support and create a tutorial #8328)docker.md—docker buildhas no--env-fileflag; the Custom Images example now uses the--build-arg FEATURES=...form the same page already shows further downmining-docker.md— bare-e MINER_ADDRESSdoes nothing on a zebrad container (only the compose stack consumes it); both examples now useZEBRA_MINING__MINER_ADDRESSperdocker.md; thet3.../P2SHexample address is no longer described as "t1… P2PKH"; added a pointer to the ready-madedocker/mining/compose stackmetrics.md— prebuilt binaries and Docker images already includeprometheus(it's indefault-release-binaries), so the page no longer tells those users to rebuild; the Prometheus config mount path now points atdocker/observability/prometheus/prometheus.yaml, where the file actually livesprofiling-and-benchmarking.md—cargo build --profile profilingfails (no such profile in any workspace manifest); use the release profileTests
Built the book locally with
mdbook build book(withmdbook-mermaid) — clean build, all six pages render correctly with the changes. Each factual claim was checked against the current manifests/configs cited above.Specifications & References
zebrad/Cargo.toml,Cargo.toml(MSRV);zebra-network/Cargo.toml(tor);docker/mining/docker-compose.yml(env vars);docker/observability/prometheus/prometheus.yamlFollow-up Work
#10948 (stale book content) and #10949 (broken links / orphaned pages) from the same audit — happy to pick these up next if this lands well.
AI disclosure (per CONTRIBUTING.md): prepared with Claude — used for verifying each claim against the codebase, drafting the edits, and building the book. I reviewed every line and can speak to each change.