From 0c1abadd0ef2e41768c362ea30c73fd93ecfc682 Mon Sep 17 00:00:00 2001 From: Marek Date: Thu, 18 May 2023 23:25:05 +0200 Subject: [PATCH] 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 --------- Co-authored-by: Alfredo Garcia --- README.md | 111 ++++------------------------------ book/src/SUMMARY.md | 3 +- book/src/user/requirements.md | 102 ++++++++++++++++++++++--------- 3 files changed, 87 insertions(+), 129 deletions(-) diff --git a/README.md b/README.md index 2325345b1..c1031e70f 100644 --- a/README.md +++ b/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 diff --git a/book/src/SUMMARY.md b/book/src/SUMMARY.md index 7debe479c..a98c39c5e 100644 --- a/book/src/SUMMARY.md +++ b/book/src/SUMMARY.md @@ -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) diff --git a/book/src/user/requirements.md b/book/src/user/requirements.md index c57010456..70ee6b00c 100644 --- a/book/src/user/requirements.md +++ b/book/src/user/requirements.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 +```