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)
|
- [Using Zebra](#using-zebra)
|
||||||
- [Release Candidates](#release-candidates)
|
- [Release Candidates](#release-candidates)
|
||||||
- [Getting Started](#getting-started)
|
- [Getting Started](#getting-started)
|
||||||
|
- [Docker](#docker)
|
||||||
- [Building Zebra](#building-zebra)
|
- [Building Zebra](#building-zebra)
|
||||||
- [Optional Features](#optional-features)
|
- [Optional Features](#optional-features)
|
||||||
- [Configuring JSON-RPC for lightwalletd](#configuring-json-rpc-for-lightwalletd)
|
- [Configuring JSON-RPC for lightwalletd](#configuring-json-rpc-for-lightwalletd)
|
||||||
- [System Requirements](#system-requirements)
|
- [Network Ports](#network-ports)
|
||||||
- [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)
|
|
||||||
- [Known Issues](#known-issues)
|
- [Known Issues](#known-issues)
|
||||||
- [Future Work](#future-work)
|
- [Future Work](#future-work)
|
||||||
- [Documentation](#documentation)
|
- [Documentation](#documentation)
|
||||||
|
|
@ -73,7 +68,12 @@ Zebra validates blocks and transactions, but needs extra software to generate th
|
||||||
|
|
||||||
## Getting Started
|
## 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:
|
This command will run our latest release, and sync it to the tip:
|
||||||
|
|
||||||
```sh
|
```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.
|
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).
|
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
|
### Network Ports
|
||||||
|
|
||||||
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
|
|
||||||
|
|
||||||
Zebra uses the following inbound and outbound TCP ports:
|
Zebra uses the following inbound and outbound TCP ports:
|
||||||
|
|
||||||
- 8233 on Mainnet
|
- 8233 on Mainnet
|
||||||
- 18233 on Testnet
|
- 18233 on Testnet
|
||||||
|
|
||||||
Outbound connections are required to sync, inbound connections are optional.
|
Please see the [Network
|
||||||
Zebra also needs access to the Zcash DNS seeders, via the OS DNS resolver (usually port 53).
|
Requirements](https://zebra.zfnd.org/user/requirements.html#network-requirements-and-ports)
|
||||||
|
section of the Zebra book for more details.
|
||||||
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.
|
|
||||||
|
|
||||||
## Known Issues
|
## Known Issues
|
||||||
|
|
||||||
|
|
|
||||||
|
|
@ -1,8 +1,9 @@
|
||||||
# Summary
|
# Summary
|
||||||
|
|
||||||
[Zebra](README.md)
|
[Zebra](README.md)
|
||||||
|
|
||||||
- [User Documentation](user.md)
|
- [User Documentation](user.md)
|
||||||
- [Zebra System Requirements](user/requirements.md)
|
- [System Requirements](user/requirements.md)
|
||||||
- [Supported Platforms](user/supported-platforms.md)
|
- [Supported Platforms](user/supported-platforms.md)
|
||||||
- [Platform Tier Policy](user/target-tier-policies.md)
|
- [Platform Tier Policy](user/target-tier-policies.md)
|
||||||
- [Installing Zebra](user/install.md)
|
- [Installing Zebra](user/install.md)
|
||||||
|
|
|
||||||
|
|
@ -1,46 +1,90 @@
|
||||||
# System Requirements
|
# System Requirements
|
||||||
|
|
||||||
We usually build `zebrad` on systems with:
|
We recommend the following requirements for compiling and running `zebrad`:
|
||||||
|
|
||||||
- 2+ CPU cores
|
- 4 CPU cores
|
||||||
- 7+ GB RAM
|
- 16 GB RAM
|
||||||
- 14+ GB of disk space
|
- 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
|
Zebra's tests can take over an hour, depending on your machine. Note that you
|
||||||
it's less fast.
|
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
|
Zebra uses around 300 GB for cached Mainnet data, and 10 GB for cached Testnet
|
||||||
- Ubuntu 18.04 / the latest LTS
|
data. We expect disk usage to grow over time.
|
||||||
- Debian Buster
|
|
||||||
|
|
||||||
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
|
## Network Requirements and Ports
|
||||||
- 16+ GB RAM
|
|
||||||
- 50GB+ available disk space for finalized state
|
|
||||||
- 100+ Mbps network connections
|
|
||||||
|
|
||||||
`zebrad` might build and run fine on smaller and slower systems - we haven't
|
Zebra uses the following inbound and outbound TCP ports:
|
||||||
tested its exact limits yet.
|
|
||||||
|
|
||||||
# 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
|
## Sentry Production Monitoring
|
||||||
|
|
||||||
Compile Zebra with `--features sentry` to monitor it using Sentry in production.
|
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`
|
- macOS,
|
||||||
- install a `lightwalletd` binary
|
- Ubuntu,
|
||||||
- Zebra's tests currently target [adityapk00/lightwalletd](https://github.com/adityapk00/lightwalletd)
|
- Docker:
|
||||||
- some tests might fail on other lightwalletd versions, due to differences in the logs
|
- Debian Bullseye.
|
||||||
- install the `protoc` Protobuf compiler:
|
|
||||||
- the `protobuf-compiler` or `protobuf` package, or
|
## Memory Issues
|
||||||
- `cmake` to automatically compile `protoc` in the `zebrad` build script
|
|
||||||
- set the required test environmental variables:
|
- If Zebra's build runs out of RAM, try setting `export CARGO_BUILD_JOBS=2`.
|
||||||
- TODO: list or link to test environmental variables - [see ticket #4363](https://github.com/ZcashFoundation/zebra/issues/4363)
|
- 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