change(docs): Refactor the system requirements (#6697)
* Simplify the summary in the book * Refactor the system requirements * Apply suggestions from code review Co-authored-by: Alfredo Garcia <oxarbitrage@gmail.com> --------- Co-authored-by: Alfredo Garcia <oxarbitrage@gmail.com>
This commit is contained in:
Marek
GitHub
parent
de08b01fd4
commit
0c1abadd0e
111
README.md
111
README.md
|
|
@ -13,16 +13,11 @@
|
|||
- [Using Zebra](#using-zebra)
|
||||
- [Release Candidates](#release-candidates)
|
||||
- [Getting Started](#getting-started)
|
||||
- [Docker](#docker)
|
||||
- [Building Zebra](#building-zebra)
|
||||
- [Optional Features](#optional-features)
|
||||
- [Configuring JSON-RPC for lightwalletd](#configuring-json-rpc-for-lightwalletd)
|
||||
- [System Requirements](#system-requirements)
|
||||
- [Memory Troubleshooting](#memory-troubleshooting)
|
||||
- [macOS Test Troubleshooting](#macos-test-troubleshooting)
|
||||
- [Network Ports and Data Usage](#network-ports-and-data-usage)
|
||||
- [Network Troubleshooting](#network-troubleshooting)
|
||||
- [Disk Usage](#disk-usage)
|
||||
- [Disk Troubleshooting](#disk-troubleshooting)
|
||||
- [Network Ports](#network-ports)
|
||||
- [Known Issues](#known-issues)
|
||||
- [Future Work](#future-work)
|
||||
- [Documentation](#documentation)
|
||||
|
|
@ -73,7 +68,12 @@ Zebra validates blocks and transactions, but needs extra software to generate th
|
|||
|
||||
## Getting Started
|
||||
|
||||
You can run Zebra using our Docker image.
|
||||
You can run Zebra using our Docker image or you can build it manually. Please
|
||||
see the [requirements section of the Zebra Book](https://zebra.zfnd.org/user/requirements.html) for system
|
||||
requirements.
|
||||
|
||||
### Docker
|
||||
|
||||
This command will run our latest release, and sync it to the tip:
|
||||
|
||||
```sh
|
||||
|
|
@ -176,103 +176,16 @@ See the [RPC config documentation](https://doc.zebra.zfnd.org/zebra_rpc/config/s
|
|||
It is recommended to use [adityapk00/lightwalletd](https://github.com/adityapk00/lightwalletd) because that is used in testing.
|
||||
Other `lightwalletd` forks have limited support, see the [detailed `lightwalletd` instructions](https://github.com/ZcashFoundation/zebra/blob/main/book/src/user/lightwalletd.md#sync-lightwalletd).
|
||||
|
||||
### System Requirements
|
||||
|
||||
The recommended requirements for compiling and running `zebrad` are:
|
||||
|
||||
- 4 CPU cores
|
||||
- 16 GB RAM
|
||||
- 300 GB available disk space for building binaries and storing cached chain state
|
||||
- 100 Mbps network connection, with 300 GB of uploads and downloads per month
|
||||
|
||||
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 Bullseye
|
||||
|
||||
Zebra's tests can take over an hour, depending on your machine.
|
||||
We're working on making them faster.
|
||||
|
||||
`zebrad` might build and run fine on smaller and slower systems - we haven't
|
||||
tested its exact limits yet.
|
||||
|
||||
For more detailed requirements, refer to the [documentation](https://zebra.zfnd.org/user/requirements.html).
|
||||
|
||||
#### Memory Troubleshooting
|
||||
|
||||
If Zebra's build runs out of RAM, try setting:
|
||||
`export CARGO_BUILD_JOBS=2`
|
||||
|
||||
If Zebra's tests timeout or run out of RAM, try running:
|
||||
`cargo test -- --test-threads=2`
|
||||
|
||||
(cargo uses all the processor cores on your machine by default.)
|
||||
|
||||
#### macOS Test Troubleshooting
|
||||
|
||||
Some of Zebra's tests deliberately cause errors that make Zebra panic.
|
||||
macOS records these panics as crash reports.
|
||||
|
||||
If you are seeing "Crash Reporter" dialogs during Zebra tests,
|
||||
you can disable them using this Terminal.app command:
|
||||
|
||||
```sh
|
||||
defaults write com.apple.CrashReporter DialogType none
|
||||
```
|
||||
|
||||
### Network Ports and Data Usage
|
||||
### Network Ports
|
||||
|
||||
Zebra uses the following inbound and outbound TCP ports:
|
||||
|
||||
- 8233 on Mainnet
|
||||
- 18233 on Testnet
|
||||
|
||||
Outbound connections are required to sync, inbound connections are optional.
|
||||
Zebra also needs access to the Zcash DNS seeders, via the OS DNS resolver (usually port 53).
|
||||
|
||||
Zebra needs some peers which have a round-trip latency of 2 seconds or less.
|
||||
If this is a problem for you, please
|
||||
[open a ticket.](https://github.com/ZcashFoundation/zebra/issues/new/choose)
|
||||
|
||||
`zebrad`'s typical mainnet network usage is:
|
||||
|
||||
- Initial sync: 100 GB download, we expect the initial download to grow to hundreds of gigabytes over time
|
||||
- Ongoing updates: 10 MB - 10 GB upload and download per day, depending on user-created transaction size and peer requests
|
||||
|
||||
Zebra performs an initial sync every time its internal database version changes,
|
||||
so some version upgrades might require a full download of the whole chain.
|
||||
|
||||
For more detailed information, refer to the [documentation](https://zebra.zfnd.org/user/run.html).
|
||||
|
||||
#### Network Troubleshooting
|
||||
|
||||
Some of Zebra's tests download Zcash blocks, so they might be unreliable depending on your network connection.
|
||||
You can set `ZEBRA_SKIP_NETWORK_TESTS=1` to skip the network tests.
|
||||
|
||||
Zebra may be unreliable on Testnet, and under less-than-perfect network conditions.
|
||||
See our [roadmap](#future-work) for details.
|
||||
|
||||
### Disk Usage
|
||||
|
||||
Zebra uses around 200 GB of space for cached mainnet data, and 10 GB of space for cached testnet data.
|
||||
We expect disk usage to grow over time, so we recommend reserving at least 300 GB for mainnet nodes.
|
||||
|
||||
Zebra's database cleans up outdated data periodically, and when Zebra is shut down and restarted.
|
||||
|
||||
#### Disk Troubleshooting
|
||||
|
||||
Zebra's state commits changes using RocksDB database transactions.
|
||||
|
||||
If you forcibly terminate Zebra, or it panics,
|
||||
any incomplete changes will be rolled back the next time it starts.
|
||||
|
||||
So Zebra's state should always be valid, unless your OS or disk hardware is corrupting data.
|
||||
Please see the [Network
|
||||
Requirements](https://zebra.zfnd.org/user/requirements.html#network-requirements-and-ports)
|
||||
section of the Zebra book for more details.
|
||||
|
||||
## Known Issues
|
||||
|
||||
|
|
|
|||
|
|
@ -1,8 +1,9 @@
|
|||
# Summary
|
||||
|
||||
[Zebra](README.md)
|
||||
|
||||
- [User Documentation](user.md)
|
||||
- [Zebra System Requirements](user/requirements.md)
|
||||
- [System Requirements](user/requirements.md)
|
||||
- [Supported Platforms](user/supported-platforms.md)
|
||||
- [Platform Tier Policy](user/target-tier-policies.md)
|
||||
- [Installing Zebra](user/install.md)
|
||||
|
|
|
|||
|
|
@ -1,46 +1,90 @@
|
|||
# System Requirements
|
||||
|
||||
We usually build `zebrad` on systems with:
|
||||
We recommend the following requirements for compiling and running `zebrad`:
|
||||
|
||||
- 2+ CPU cores
|
||||
- 7+ GB RAM
|
||||
- 14+ GB of disk space
|
||||
- 4 CPU cores
|
||||
- 16 GB RAM
|
||||
- 300 GB available disk space for building binaries and storing cached chain
|
||||
state
|
||||
- 100 Mbps network connection, with 300 GB of uploads and downloads per month
|
||||
|
||||
On many-core machines (like, 32-core) the build is very fast; on 2-core machines
|
||||
it's less fast.
|
||||
Zebra's tests can take over an hour, depending on your machine. Note that you
|
||||
might be able to build and run Zebra on slower systems — we haven't tested its
|
||||
exact limits yet.
|
||||
|
||||
We continuously test that our builds and tests pass on:
|
||||
## Disk Requirements
|
||||
|
||||
- macOS Big Sur 11.0
|
||||
- Ubuntu 18.04 / the latest LTS
|
||||
- Debian Buster
|
||||
Zebra uses around 300 GB for cached Mainnet data, and 10 GB for cached Testnet
|
||||
data. We expect disk usage to grow over time.
|
||||
|
||||
We usually run `zebrad` on systems with:
|
||||
Zebra cleans up its database periodically, and also when you shut it down or
|
||||
restart it. Changes are committed using RocksDB database transactions. If you
|
||||
forcibly terminate Zebra, or it panics, any incomplete changes will be rolled
|
||||
back the next time it starts. So Zebra's state should always be valid, unless
|
||||
your OS or disk hardware is corrupting data.
|
||||
|
||||
- 4+ CPU cores
|
||||
- 16+ GB RAM
|
||||
- 50GB+ available disk space for finalized state
|
||||
- 100+ Mbps network connections
|
||||
## Network Requirements and Ports
|
||||
|
||||
`zebrad` might build and run fine on smaller and slower systems - we haven't
|
||||
tested its exact limits yet.
|
||||
Zebra uses the following inbound and outbound TCP ports:
|
||||
|
||||
# Additional Features
|
||||
- 8233 on Mainnet
|
||||
- 18233 on Testnet
|
||||
|
||||
Outbound connections are required to sync, inbound connections are optional.
|
||||
Zebra also needs access to the Zcash DNS seeders, via the OS DNS resolver
|
||||
(usually port 53).
|
||||
|
||||
The typical Mainnet network usage is:
|
||||
|
||||
- Initial sync: 300 GB download, as already noted, we expect the initial
|
||||
download to grow.
|
||||
- Ongoing updates: 10 MB - 10 GB upload and download per day, depending on
|
||||
user-created transaction size and peer requests.
|
||||
|
||||
Zebra performs an initial sync every time its internal database version changes,
|
||||
so some version upgrades might require a full download of the whole chain.
|
||||
|
||||
Zebra needs some peers which have a round-trip latency of 2 seconds or less. If
|
||||
this is a problem for you, please [open a
|
||||
ticket.](https://github.com/ZcashFoundation/zebra/issues/new/choose)
|
||||
|
||||
## Sentry Production Monitoring
|
||||
|
||||
Compile Zebra with `--features sentry` to monitor it using Sentry in production.
|
||||
|
||||
## Lightwalletd Test Requirements
|
||||
# Troubleshooting
|
||||
|
||||
To test Zebra's `lightwalletd` RPC methods:
|
||||
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:
|
||||
|
||||
- compile Zebra with the `--features lightwalletd-grpc-tests`
|
||||
- install a `lightwalletd` binary
|
||||
- Zebra's tests currently target [adityapk00/lightwalletd](https://github.com/adityapk00/lightwalletd)
|
||||
- some tests might fail on other lightwalletd versions, due to differences in the logs
|
||||
- install the `protoc` Protobuf compiler:
|
||||
- the `protobuf-compiler` or `protobuf` package, or
|
||||
- `cmake` to automatically compile `protoc` in the `zebrad` build script
|
||||
- set the required test environmental variables:
|
||||
- TODO: list or link to test environmental variables - [see ticket #4363](https://github.com/ZcashFoundation/zebra/issues/4363)
|
||||
- macOS,
|
||||
- Ubuntu,
|
||||
- Docker:
|
||||
- Debian Bullseye.
|
||||
|
||||
## Memory Issues
|
||||
|
||||
- If Zebra's build runs out of RAM, try setting `export CARGO_BUILD_JOBS=2`.
|
||||
- If Zebra's tests timeout or run out of RAM, try running `cargo test -- --test-threads=2`. Note that `cargo` uses all processor cores on your machine
|
||||
by default.
|
||||
|
||||
## Network Issues
|
||||
|
||||
- Some of Zebra's tests download Zcash blocks, so they might be unreliable
|
||||
depending on your network connection. You can set `ZEBRA_SKIP_NETWORK_TESTS=1`
|
||||
to skip the network tests.
|
||||
- Zebra may be unreliable on Testnet, and under less-than-perfect network
|
||||
conditions. See our [future
|
||||
work](https://github.com/ZcashFoundation/zebra#future-work) for details.
|
||||
|
||||
## Issues with Tests on macOS
|
||||
|
||||
Some of Zebra's tests deliberately cause errors that make Zebra panic. macOS
|
||||
records these panics as crash reports. If you are seeing "Crash Reporter"
|
||||
dialogs during Zebra tests, you can disable them using this Terminal.app
|
||||
command:
|
||||
|
||||
```sh
|
||||
defaults write com.apple.CrashReporter DialogType none
|
||||
```
|
||||
|
|
|
|||
Loading…
Reference in New Issue