Refactor `README.md` and docs (#8654)
* Move "Known Issues" from README to the book * Remove an old note from the book * Move optional configs & features to the book * Fix TOC in `README.md` * Refactor the section on installing Zebra * Fix badges in `README.md` * Mention optional features and troubleshooting
This commit is contained in:
parent
ecdc8c3b0b
commit
5ff2563542
81
README.md
81
README.md
|
@ -2,18 +2,13 @@
|
||||||
|
|
||||||
---
|
---
|
||||||
|
|
||||||
[![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)
|
![License](https://img.shields.io/badge/license-MIT%2FApache--2.0-blue.svg)
|
||||||
|
|
||||||
## Contents
|
|
||||||
|
|
||||||
- [About](#about)
|
- [About](#about)
|
||||||
- [Getting Started](#getting-started)
|
- [Getting Started](#getting-started)
|
||||||
- [Docker](#docker)
|
- [Docker](#docker)
|
||||||
- [Building Zebra](#building-zebra)
|
- [Building Zebra](#building-zebra)
|
||||||
- [Optional Configs & Features](#optional-configs--features)
|
|
||||||
- [Known Issues](#known-issues)
|
|
||||||
- [Future Work](#future-work)
|
|
||||||
- [Documentation](#documentation)
|
- [Documentation](#documentation)
|
||||||
- [User support](#user-support)
|
- [User support](#user-support)
|
||||||
- [Security](#security)
|
- [Security](#security)
|
||||||
|
@ -123,69 +118,9 @@ You can start Zebra by
|
||||||
zebrad start
|
zebrad start
|
||||||
```
|
```
|
||||||
|
|
||||||
See the [Installing Zebra](https://zebra.zfnd.org/user/install.html) and [Running Zebra](https://zebra.zfnd.org/user/run.html)
|
Refer to the [Installing Zebra](https://zebra.zfnd.org/user/install.html) and
|
||||||
sections in the book for more details.
|
[Running Zebra](https://zebra.zfnd.org/user/run.html) sections in the book for
|
||||||
|
enabling optional features, detailed configuration and further 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="<feature1> <feature2> ..." ...
|
|
||||||
```
|
|
||||||
|
|
||||||
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.
|
|
||||||
|
|
||||||
## 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
|
## Documentation
|
||||||
|
|
||||||
|
@ -207,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+).
|
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
|
## Security
|
||||||
|
|
||||||
|
|
|
@ -1,18 +1,75 @@
|
||||||
# Installing Zebra
|
# 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
|
## Optional Configs & Features
|
||||||
|
|
||||||
To compile Zebra from source, you will need to [install some dependencies.](https://zebra.zfnd.org/index.html#building-zebra).
|
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="<feature1> <feature2> ..." ...
|
||||||
|
```
|
||||||
|
|
||||||
|
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
|
## Alternative Compilation Methods
|
||||||
|
|
||||||
|
Zebra also supports the following compilation methods.
|
||||||
|
|
||||||
### Compiling Manually from git
|
### Compiling Manually from git
|
||||||
|
|
||||||
To compile Zebra directly from GitHub, or from a GitHub release source archive:
|
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
|
2. Get the source code using `git` or from a GitHub source package
|
||||||
|
|
||||||
|
@ -74,4 +131,3 @@ cargo build
|
||||||
cargo build -p zebrad --all-features
|
cargo build -p zebrad --all-features
|
||||||
```
|
```
|
||||||
|
|
||||||
|
|
||||||
|
|
|
@ -1,13 +1,18 @@
|
||||||
# Troubleshooting
|
# Troubleshooting
|
||||||
|
|
||||||
We continuously test that our builds and tests pass on the _latest_ [GitHub
|
## Known Issues
|
||||||
Runners](https://docs.github.com/en/actions/using-github-hosted-runners/about-github-hosted-runners#supported-runners-and-hardware-resources)
|
|
||||||
for:
|
|
||||||
|
|
||||||
- macOS,
|
There are a few bugs in Zebra that we're still working on fixing:
|
||||||
- Ubuntu,
|
|
||||||
- Docker:
|
- [The `getpeerinfo` RPC shows current and recent outbound connections](https://github.com/ZcashFoundation/zebra/issues/7893), rather than current inbound and outbound connections.
|
||||||
- Debian Bookworm.
|
|
||||||
|
- [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
|
## Memory Issues
|
||||||
|
|
||||||
|
|
Loading…
Reference in New Issue