From 50e34a0001b4a1129d29edf63742e30faadd83e9 Mon Sep 17 00:00:00 2001 From: Marek Date: Fri, 28 Jun 2024 09:49:27 +0200 Subject: [PATCH 1/7] Move "Known Issues" from README to the book --- README.md | 14 -------------- book/src/user/troubleshooting.md | 14 ++++++++++++++ 2 files changed, 14 insertions(+), 14 deletions(-) diff --git a/README.md b/README.md index ad29727236f..3ce1f7fc3bb 100644 --- a/README.md +++ b/README.md @@ -173,20 +173,6 @@ Our full list of experimental and developer features is in [the API documentatio Some debugging and monitoring features are disabled in release builds to increase performance. -## Known Issues - -There are a few bugs in Zebra that we're still working on fixing: - -- [The `getpeerinfo` RPC shows current and recent outbound connections](https://github.com/ZcashFoundation/zebra/issues/7893), rather than current inbound and outbound connections. - -- [Progress bar estimates can become extremely large](https://github.com/console-rs/indicatif/issues/556). We're waiting on a fix in the progress bar library. - -- Zebra currently gossips and connects to [private IP addresses](https://en.wikipedia.org/wiki/IP_address#Private_addresses), we want to [disable private IPs but provide a config (#3117)](https://github.com/ZcashFoundation/zebra/issues/3117) in an upcoming release - -- Block download and verification sometimes times out during Zebra's initial sync [#5709](https://github.com/ZcashFoundation/zebra/issues/5709). The full sync still finishes reasonably quickly. - -- Experimental Tor support is disabled until Zebra upgrades to the latest `arti-client`. This happened due to a Rust dependency conflict ([#5492](https://github.com/ZcashFoundation/zebra/issues/5492)) and is still an issue due to [another dependency conflict](https://github.com/ZcashFoundation/zebra/issues/8328#issuecomment-1969989648). - ## Documentation The Zcash Foundation maintains the following resources documenting Zebra: diff --git a/book/src/user/troubleshooting.md b/book/src/user/troubleshooting.md index 8a92125fa29..4ad7b92e980 100644 --- a/book/src/user/troubleshooting.md +++ b/book/src/user/troubleshooting.md @@ -8,6 +8,20 @@ for: - Ubuntu, - Docker: - Debian Bookworm. + +## Known Issues + +There are a few bugs in Zebra that we're still working on fixing: + +- [The `getpeerinfo` RPC shows current and recent outbound connections](https://github.com/ZcashFoundation/zebra/issues/7893), rather than current inbound and outbound connections. + +- [Progress bar estimates can become extremely large](https://github.com/console-rs/indicatif/issues/556). We're waiting on a fix in the progress bar library. + +- Zebra currently gossips and connects to [private IP addresses](https://en.wikipedia.org/wiki/IP_address#Private_addresses), we want to [disable private IPs but provide a config (#3117)](https://github.com/ZcashFoundation/zebra/issues/3117) in an upcoming release + +- Block download and verification sometimes times out during Zebra's initial sync [#5709](https://github.com/ZcashFoundation/zebra/issues/5709). The full sync still finishes reasonably quickly. + +- Experimental Tor support is disabled until Zebra upgrades to the latest `arti-client`. This happened due to a Rust dependency conflict ([#5492](https://github.com/ZcashFoundation/zebra/issues/5492)) and is still an issue due to [another dependency conflict](https://github.com/ZcashFoundation/zebra/issues/8328#issuecomment-1969989648). ## Memory Issues From 2cd5142fa8265c82e1a306ab89486b1269467ff4 Mon Sep 17 00:00:00 2001 From: Marek Date: Fri, 28 Jun 2024 09:50:05 +0200 Subject: [PATCH 2/7] Remove an old note from the book --- book/src/user/troubleshooting.md | 9 --------- 1 file changed, 9 deletions(-) diff --git a/book/src/user/troubleshooting.md b/book/src/user/troubleshooting.md index 4ad7b92e980..009e079cdc9 100644 --- a/book/src/user/troubleshooting.md +++ b/book/src/user/troubleshooting.md @@ -1,14 +1,5 @@ # Troubleshooting -We continuously test that our builds and tests pass on the _latest_ [GitHub -Runners](https://docs.github.com/en/actions/using-github-hosted-runners/about-github-hosted-runners#supported-runners-and-hardware-resources) -for: - -- macOS, -- Ubuntu, -- Docker: - - Debian Bookworm. - ## Known Issues There are a few bugs in Zebra that we're still working on fixing: From 66f387ad227c9106f8c4abffcb03fac75c647d5d Mon Sep 17 00:00:00 2001 From: Marek Date: Fri, 28 Jun 2024 10:30:54 +0200 Subject: [PATCH 3/7] Move optional configs & features to the book --- README.md | 47 -------------------------------- book/src/user/install.md | 58 ++++++++++++++++++++++++++++++++++++++++ 2 files changed, 58 insertions(+), 47 deletions(-) diff --git a/README.md b/README.md index 3ce1f7fc3bb..c49bff929d8 100644 --- a/README.md +++ b/README.md @@ -126,53 +126,6 @@ zebrad start See the [Installing Zebra](https://zebra.zfnd.org/user/install.html) and [Running Zebra](https://zebra.zfnd.org/user/run.html) sections in the book for more details. -#### Optional Configs & Features - -##### Initializing Configuration File - -```console -zebrad generate -o ~/.config/zebrad.toml -``` - -The above command places the generated `zebrad.toml` config file in the default preferences directory of Linux. For other OSes default locations [see here](https://docs.rs/dirs/latest/dirs/fn.preference_dir.html). - -##### Configuring Progress Bars - -Configure `tracing.progress_bar` in your `zebrad.toml` to -[show key metrics in the terminal using progress bars](https://zfnd.org/experimental-zebra-progress-bars/). -When progress bars are active, Zebra automatically sends logs to a file. - -There is a known issue where [progress bar estimates become extremely large](https://github.com/console-rs/indicatif/issues/556). - -In future releases, the `progress_bar = "summary"` config will show a few key metrics, -and the "detailed" config will show all available metrics. Please let us know which metrics are -important to you! - -##### Configuring Mining - -Zebra can be configured for mining by passing a `MINER_ADDRESS` and port mapping to Docker. -See the [mining support docs](https://zebra.zfnd.org/user/mining-docker.html) for more details. - -##### Custom Build Features - -You can also build Zebra with additional [Cargo features](https://doc.rust-lang.org/cargo/reference/features.html#command-line-feature-options): - -- `prometheus` for [Prometheus metrics](https://zebra.zfnd.org/user/metrics.html) -- `sentry` for [Sentry monitoring](https://zebra.zfnd.org/user/tracing.html#sentry-production-monitoring) -- `elasticsearch` for [experimental Elasticsearch support](https://zebra.zfnd.org/user/elasticsearch.html) -- `shielded-scan` for [experimental shielded scan support](https://zebra.zfnd.org/user/shielded-scan.html) - -You can combine multiple features by listing them as parameters of the `--features` flag: - -```sh -cargo install --features=" ..." ... -``` - -Our full list of experimental and developer features is in [the API documentation](https://docs.rs/zebrad/latest/zebrad/index.html#zebra-feature-flags). - -Some debugging and monitoring features are disabled in release builds to increase -performance. - ## Documentation The Zcash Foundation maintains the following resources documenting Zebra: diff --git a/book/src/user/install.md b/book/src/user/install.md index 46304726b1f..23a3a313bfa 100644 --- a/book/src/user/install.md +++ b/book/src/user/install.md @@ -6,6 +6,64 @@ Follow the [Docker or compilation instructions](https://zebra.zfnd.org/index.htm To compile Zebra from source, you will need to [install some dependencies.](https://zebra.zfnd.org/index.html#building-zebra). +#### Optional Configs & Features + +Zebra supports a variety of optional features which you can enable and configure +manually. + +##### Initializing Configuration File + +```console +zebrad generate -o ~/.config/zebrad.toml +``` + +The above command places the generated `zebrad.toml` config file in the default +preferences directory of Linux. For other OSes default locations [see +here](https://docs.rs/dirs/latest/dirs/fn.preference_dir.html). + +##### Configuring Progress Bars + +Configure `tracing.progress_bar` in your `zebrad.toml` to [show key metrics in +the terminal using progress +bars](https://zfnd.org/experimental-zebra-progress-bars/). When progress bars +are active, Zebra automatically sends logs to a file. + +There is a known issue where [progress bar estimates become extremely +large](https://github.com/console-rs/indicatif/issues/556). + +In future releases, the `progress_bar = "summary"` config will show a few key +metrics, and the "detailed" config will show all available metrics. Please let +us know which metrics are important to you! + +##### Configuring Mining + +Zebra can be configured for mining by passing a `MINER_ADDRESS` and port mapping +to Docker. See the [mining support +docs](https://zebra.zfnd.org/user/mining-docker.html) for more details. + +##### Custom Build Features + +You can also build Zebra with additional [Cargo +features](https://doc.rust-lang.org/cargo/reference/features.html#command-line-feature-options): + +- `prometheus` for [Prometheus metrics](https://zebra.zfnd.org/user/metrics.html) +- `sentry` for [Sentry monitoring](https://zebra.zfnd.org/user/tracing.html#sentry-production-monitoring) +- `elasticsearch` for [experimental Elasticsearch support](https://zebra.zfnd.org/user/elasticsearch.html) +- `shielded-scan` for [experimental shielded scan support](https://zebra.zfnd.org/user/shielded-scan.html) + +You can combine multiple features by listing them as parameters of the +`--features` flag: + +```sh +cargo install --features=" ..." ... +``` + +Our full list of experimental and developer features is in [the API +documentation](https://docs.rs/zebrad/latest/zebrad/index.html#zebra-feature-flags). + +Some debugging and monitoring features are disabled in release builds to +increase performance. + ## Alternative Compilation Methods ### Compiling Manually from git From 5e92ab8f1b8daf164595155449a3e08000ba7079 Mon Sep 17 00:00:00 2001 From: Marek Date: Fri, 28 Jun 2024 10:31:43 +0200 Subject: [PATCH 4/7] Fix TOC in `README.md` --- README.md | 5 ----- 1 file changed, 5 deletions(-) diff --git a/README.md b/README.md index c49bff929d8..8edf6eaf624 100644 --- a/README.md +++ b/README.md @@ -5,15 +5,10 @@ [![CI Docker](https://github.com/ZcashFoundation/zebra/actions/workflows/ci-integration-tests-gcp.yml/badge.svg)](https://github.com/ZcashFoundation/zebra/actions/workflows/ci-integration-tests-gcp.yml) [![CI OSes](https://github.com/ZcashFoundation/zebra/actions/workflows/ci-unit-tests-os.yml/badge.svg)](https://github.com/ZcashFoundation/zebra/actions/workflows/ci-unit-tests-os.yml) [![Continuous Delivery](https://github.com/ZcashFoundation/zebra/actions/workflows/cd-deploy-nodes-gcp.yml/badge.svg)](https://github.com/ZcashFoundation/zebra/actions/workflows/cd-deploy-nodes-gcp.yml) [![codecov](https://codecov.io/gh/ZcashFoundation/zebra/branch/main/graph/badge.svg)](https://codecov.io/gh/ZcashFoundation/zebra) [![Build docs](https://github.com/ZcashFoundation/zebra/actions/workflows/docs-deploy-firebase.yml/badge.svg)](https://github.com/ZcashFoundation/zebra/actions/workflows/docs-deploy-firebase.yml) ![License](https://img.shields.io/badge/license-MIT%2FApache--2.0-blue.svg) -## Contents - - [About](#about) - [Getting Started](#getting-started) - [Docker](#docker) - [Building Zebra](#building-zebra) - - [Optional Configs & Features](#optional-configs--features) -- [Known Issues](#known-issues) -- [Future Work](#future-work) - [Documentation](#documentation) - [User support](#user-support) - [Security](#security) From 738337480891d26681ab818e34eb9a363a720ed5 Mon Sep 17 00:00:00 2001 From: Marek Date: Fri, 28 Jun 2024 11:24:00 +0200 Subject: [PATCH 5/7] Refactor the section on installing Zebra --- book/src/user/install.md | 22 ++++++++++------------ 1 file changed, 10 insertions(+), 12 deletions(-) diff --git a/book/src/user/install.md b/book/src/user/install.md index 23a3a313bfa..c69c0dfce81 100644 --- a/book/src/user/install.md +++ b/book/src/user/install.md @@ -1,17 +1,13 @@ # Installing Zebra -Follow the [Docker or compilation instructions](https://zebra.zfnd.org/index.html#getting-started). +To install Zebra, follow the [Getting Started](https://zebra.zfnd.org/index.html#getting-started) section. -## Installing Dependencies - -To compile Zebra from source, you will need to [install some dependencies.](https://zebra.zfnd.org/index.html#building-zebra). - -#### Optional Configs & Features +## Optional Configs & Features Zebra supports a variety of optional features which you can enable and configure manually. -##### Initializing Configuration File +### Initializing Configuration File ```console zebrad generate -o ~/.config/zebrad.toml @@ -21,7 +17,7 @@ The above command places the generated `zebrad.toml` config file in the default preferences directory of Linux. For other OSes default locations [see here](https://docs.rs/dirs/latest/dirs/fn.preference_dir.html). -##### Configuring Progress Bars +### Configuring Progress Bars Configure `tracing.progress_bar` in your `zebrad.toml` to [show key metrics in the terminal using progress @@ -35,13 +31,13 @@ In future releases, the `progress_bar = "summary"` config will show a few key metrics, and the "detailed" config will show all available metrics. Please let us know which metrics are important to you! -##### Configuring Mining +### Configuring Mining Zebra can be configured for mining by passing a `MINER_ADDRESS` and port mapping to Docker. See the [mining support docs](https://zebra.zfnd.org/user/mining-docker.html) for more details. -##### Custom Build Features +### Custom Build Features You can also build Zebra with additional [Cargo features](https://doc.rust-lang.org/cargo/reference/features.html#command-line-feature-options): @@ -66,11 +62,14 @@ increase performance. ## Alternative Compilation Methods +Zebra also supports the following compilation methods. + ### Compiling Manually from git To compile Zebra directly from GitHub, or from a GitHub release source archive: -1. Install the dependencies (see above) +1. Install the dependencies as described in the [Getting + Started](https://zebra.zfnd.org/index.html#getting-started) section. 2. Get the source code using `git` or from a GitHub source package @@ -132,4 +131,3 @@ cargo build cargo build -p zebrad --all-features ``` - From d2705ad6214f7aa58c8731f3f99aed3517dfe553 Mon Sep 17 00:00:00 2001 From: Marek Date: Fri, 28 Jun 2024 11:25:00 +0200 Subject: [PATCH 6/7] Fix badges in `README.md` --- README.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/README.md b/README.md index 8edf6eaf624..ffffd448c2b 100644 --- a/README.md +++ b/README.md @@ -2,7 +2,7 @@ --- -[![CI Docker](https://github.com/ZcashFoundation/zebra/actions/workflows/ci-integration-tests-gcp.yml/badge.svg)](https://github.com/ZcashFoundation/zebra/actions/workflows/ci-integration-tests-gcp.yml) [![CI OSes](https://github.com/ZcashFoundation/zebra/actions/workflows/ci-unit-tests-os.yml/badge.svg)](https://github.com/ZcashFoundation/zebra/actions/workflows/ci-unit-tests-os.yml) [![Continuous Delivery](https://github.com/ZcashFoundation/zebra/actions/workflows/cd-deploy-nodes-gcp.yml/badge.svg)](https://github.com/ZcashFoundation/zebra/actions/workflows/cd-deploy-nodes-gcp.yml) [![codecov](https://codecov.io/gh/ZcashFoundation/zebra/branch/main/graph/badge.svg)](https://codecov.io/gh/ZcashFoundation/zebra) [![Build docs](https://github.com/ZcashFoundation/zebra/actions/workflows/docs-deploy-firebase.yml/badge.svg)](https://github.com/ZcashFoundation/zebra/actions/workflows/docs-deploy-firebase.yml) +[![Integration Tests](https://github.com/ZcashFoundation/zebra/actions/workflows/sub-ci-integration-tests-gcp.yml/badge.svg)](https://github.com/ZcashFoundation/zebra/actions/workflows/sub-ci-integration-tests-gcp.yml) [![CI OSes](https://github.com/ZcashFoundation/zebra/actions/workflows/ci-unit-tests-os.yml/badge.svg)](https://github.com/ZcashFoundation/zebra/actions/workflows/ci-unit-tests-os.yml) [![Continuous Delivery](https://github.com/ZcashFoundation/zebra/actions/workflows/cd-deploy-nodes-gcp.yml/badge.svg)](https://github.com/ZcashFoundation/zebra/actions/workflows/cd-deploy-nodes-gcp.yml) [![codecov](https://codecov.io/gh/ZcashFoundation/zebra/branch/main/graph/badge.svg)](https://codecov.io/gh/ZcashFoundation/zebra) [![Build docs](https://github.com/ZcashFoundation/zebra/actions/workflows/docs-deploy-firebase.yml/badge.svg)](https://github.com/ZcashFoundation/zebra/actions/workflows/docs-deploy-firebase.yml) ![License](https://img.shields.io/badge/license-MIT%2FApache--2.0-blue.svg) - [About](#about) From 36d78ddbd65b7caf1d2da9c83cc2441e223b18c3 Mon Sep 17 00:00:00 2001 From: Marek Date: Fri, 28 Jun 2024 18:39:05 +0200 Subject: [PATCH 7/7] Mention optional features and troubleshooting --- README.md | 13 ++++++++++--- 1 file changed, 10 insertions(+), 3 deletions(-) diff --git a/README.md b/README.md index ffffd448c2b..7e5d94fbb46 100644 --- a/README.md +++ b/README.md @@ -118,8 +118,9 @@ You can start Zebra by zebrad start ``` -See the [Installing Zebra](https://zebra.zfnd.org/user/install.html) and [Running Zebra](https://zebra.zfnd.org/user/run.html) -sections in the book for more details. +Refer to the [Installing Zebra](https://zebra.zfnd.org/user/install.html) and +[Running Zebra](https://zebra.zfnd.org/user/run.html) sections in the book for +enabling optional features, detailed configuration and further details. ## Documentation @@ -141,7 +142,13 @@ The Zcash Foundation maintains the following resources documenting Zebra: For bug reports please [open a bug report ticket in the Zebra repository](https://github.com/ZcashFoundation/zebra/issues/new?assignees=&labels=C-bug%2C+S-needs-triage&projects=&template=bug_report.yml&title=%5BUser+reported+bug%5D%3A+). -Alternatively by chat, [Join the Zcash Foundation Discord Server](https://discord.com/invite/aRgNRVwsM8) and find the #zebra-support channel. +Alternatively by chat, [Join the Zcash Foundation Discord +Server](https://discord.com/invite/aRgNRVwsM8) and find the #zebra-support +channel. + +We maintain a list of known issues in the +[Troubleshooting](https://zebra.zfnd.org/user/troubleshooting.html) section of +the book. ## Security