cerc-io/lighthouse
16
0
Fork 0
Code Issues 1 Pull Requests Packages Projects Releases Wiki Activity

Update Lighthouse book and some FAQs (#4178)

Browse Source 
## Issue Addressed

Updated Lighthouse book on Section 2 and added some FAQs

## Proposed Changes

All changes are made in the book/src .md files.

## Additional Info

Please provide any additional information. For example, future considerations
or information useful for reviewers.


Co-authored-by: chonghe <tanck2005@gmail.com>
Co-authored-by: Michael Sproul <micsproul@gmail.com>
This commit is contained in:
chonghe 2023-04-14 01:11:45 +00:00
parent a3669abac5
commit 56dba96319
8 changed files with 149 additions and 88 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

1
book/src/SUMMARY.md
View File

@ -2,7 +2,6 @@
* [Introduction](./intro.md)
* [Installation](./installation.md)
* [System Requirements](./system-requirements.md)
* [Pre-Built Binaries](./installation-binaries.md)
* [Docker](./docker.md)
* [Build from Source](./installation-source.md)

41
book/src/docker.md
View File

@ -16,21 +16,18 @@ way to run Lighthouse without building the image yourself.
Obtain the latest image with:
```bash
$ docker pull sigp/lighthouse
docker pull sigp/lighthouse
```
Download and test the image with:
```bash
$ docker run sigp/lighthouse lighthouse --version
docker run sigp/lighthouse lighthouse --version
```
If you can see the latest [Lighthouse release](https://github.com/sigp/lighthouse/releases) version
(see example below), then you've successfully installed Lighthouse via Docker.
> Pro tip: try the `latest-modern` image for a 20-30% speed-up! See [Available Docker
> Images](#available-docker-images) below.
### Example Version Output
```
@ -38,6 +35,9 @@ Lighthouse vx.x.xx-xxxxxxxxx
BLS Library: xxxx-xxxxxxx
```
> Pro tip: try the `latest-modern` image for a 20-30% speed-up! See [Available Docker
> Images](#available-docker-images) below.
### Available Docker Images
There are several images available on Docker Hub.
@ -47,11 +47,10 @@ Lighthouse with optimizations enabled. If you are running on older hardware then
`latest` image bundles a _portable_ version of Lighthouse which is slower but with better hardware
compatibility (see [Portability](./installation-binaries.md#portability)).
To install a specific tag (in this case `latest-modern`) add the tag name to your `docker` commands
like so:
To install a specific tag (in this case `latest-modern`), add the tag name to your `docker` commands:
```
$ docker pull sigp/lighthouse:latest-modern
docker pull sigp/lighthouse:latest-modern
```
Image tags follow this format:
@ -65,17 +64,17 @@ The `version` is:
* `vX.Y.Z` for a tagged Lighthouse release, e.g. `v2.1.1`
* `latest` for the `stable` branch (latest release) or `unstable` branch
The `stability` is:
* `-unstable` for the `unstable` branch
* empty for a tagged release or the `stable` branch
The `arch` is:
* `-amd64` for x86_64, e.g. Intel, AMD
* `-arm64` for aarch64, e.g. Raspberry Pi 4
* empty for a multi-arch image (works on either `amd64` or `arm64` platforms)
The `stability` is:
* `-unstable` for the `unstable` branch
* empty for a tagged release or the `stable` branch
The `modernity` is:
* `-modern` for optimized builds
@ -99,13 +98,13 @@ To build the image from source, navigate to
the root of the repository and run:
```bash
$ docker build . -t lighthouse:local
docker build . -t lighthouse:local
```
The build will likely take several minutes. Once it's built, test it with:
```bash
$ docker run lighthouse:local lighthouse --help
docker run lighthouse:local lighthouse --help
```
## Using the Docker image
@ -113,12 +112,12 @@ $ docker run lighthouse:local lighthouse --help
You can run a Docker beacon node with the following command:
```bash
$ docker run -p 9000:9000/tcp -p 9000:9000/udp -p 127.0.0.1:5052:5052 -v $HOME/.lighthouse:/root/.lighthouse sigp/lighthouse lighthouse --network mainnet beacon --http --http-address 0.0.0.0
docker run -p 9000:9000/tcp -p 9000:9000/udp -p 127.0.0.1:5052:5052 -v $HOME/.lighthouse:/root/.lighthouse sigp/lighthouse lighthouse --network mainnet beacon --http --http-address 0.0.0.0
```
> To join the Prater testnet, use `--network prater` instead.
> To join the Goerli testnet, use `--network goerli` instead.
> The `-p` and `-v` and values are described below.
> The `-v` (Volumes) and `-p` (Ports) and values are described below.
### Volumes
@ -131,7 +130,7 @@ The following example runs a beacon node with the data directory
mapped to the users home directory:
```bash
$ docker run -v $HOME/.lighthouse:/root/.lighthouse sigp/lighthouse lighthouse beacon
docker run -v $HOME/.lighthouse:/root/.lighthouse sigp/lighthouse lighthouse beacon
```
### Ports
@ -140,14 +139,14 @@ In order to be a good peer and serve other peers you should expose port `9000` f
Use the `-p` flag to do this:
```bash
$ docker run -p 9000:9000/tcp -p 9000:9000/udp sigp/lighthouse lighthouse beacon
docker run -p 9000:9000/tcp -p 9000:9000/udp sigp/lighthouse lighthouse beacon
```
If you use the `--http` flag you may also want to expose the HTTP port with `-p
127.0.0.1:5052:5052`.
```bash
$ docker run -p 9000:9000/tcp -p 9000:9000/udp -p 127.0.0.1:5052:5052 sigp/lighthouse lighthouse beacon --http --http-address 0.0.0.0
docker run -p 9000:9000/tcp -p 9000:9000/udp -p 127.0.0.1:5052:5052 sigp/lighthouse lighthouse beacon --http --http-address 0.0.0.0
```
[docker_hub]: https://hub.docker.com/repository/docker/sigp/lighthouse/

50
book/src/faq.md
View File

@ -9,6 +9,11 @@
- [What is "Syncing deposit contract block cache"?](#what-is-syncing-deposit-contract-block-cache)
- [Can I use redundancy in my staking setup?](#can-i-use-redundancy-in-my-staking-setup)
- [How can I monitor my validators?](#how-can-i-monitor-my-validators)
- [I see beacon logs showing `WARN: Execution engine called failed`, what should I do?](#i-see-beacon-logs-showing-warn-execution-engine-called-failed-what-should-i-do)
- [How do I check or update my withdrawal credentials?](#how-do-i-check-or-update-my-withdrawal-credentials)
- [I am missing attestations. Why?](#i-am-missing-attestations-why)
- [Sometimes I miss the attestation head vote, resulting in penalty. Is this normal?](#sometimes-i-miss-the-attestation-head-vote-resulting-in-penalty-is-this-normal)
- [My beacon node is stuck at downloading historical block using checkpoing sync. What can I do?](#my-beacon-node-is-stuck-at-downloading-historical-block-using-checkpoing-sync-what-can-i-do)
### Why does it take so long for a validator to be activated?
@ -185,4 +190,47 @@ However, there are some components which can be configured with redundancy. See
Apart from using block explorers, you may use the "Validator Monitor" built into Lighthouse which
provides logging and Prometheus/Grafana metrics for individual validators. See [Validator
Monitoring](./validator-monitoring.md) for more information.
Monitoring](./validator-monitoring.md) for more information. Lighthouse has also developed Lighthouse UI (Siren) to monitor performance, see [Lighthouse UI (Siren)](./lighthouse-ui.md).
### I see beacon logs showing `WARN: Execution engine called failed`, what should I do?
The `WARN Execution engine called failed` log is shown when the beacon node cannot reach the execution engine. When this warning occurs, it will be followed by a detailed message. A frequently encountered example of the error message is:
`error: Reqwest(reqwest::Error { kind: Request, url: Url { scheme: "http", cannot_be_a_base: false, username: "", password: None, host: Some(Ipv4(127.0.0.1)), port: Some(8551), path: "/", query: None, fragment: None }, source: TimedOut }), service: exec`
which says `TimedOut` at the end of the message. This means that the execution engine has not responded in time to the beacon node. There are a few reasons why this can occur:
1. The execution engine is not synced. Check the log of the execution engine to make sure that it is synced. If it is syncing, wait until it is synced and the error will disappear. You will see the beacon node logs `INFO Execution engine online` when it is synced.
1. The computer is overloaded. Check the CPU and RAM usage to see if it has overloaded. You can use `htop` to check for CPU and RAM usage.
1. Your SSD is slow. Check if your SSD is in "The Bad" list [here](https://gist.github.com/yorickdowne/f3a3e79a573bf35767cd002cc977b038). If your SSD is in "The Bad" list, it means it cannot keep in sync to the network and you may want to consider upgrading to a better SSD.
If the reason for the error message is caused by no. 1 above, you may want to look further. If the execution engine is out of sync suddenly, it is usually caused by ungraceful shutdown. The common causes for ungraceful shutdown are:
- Power outage. If power outages are an issue at your place, consider getting a UPS to avoid ungraceful shutdown of services.
- The service file is not stopped properly. To overcome this, make sure that the process is stop properly, e.g., during client updates.
- Out of memory (oom) error. This can happen when the system memory usage has reached its maximum and causes the execution engine to be killed. When this occurs, the log file will show `Main process exited, code=killed, status=9/KILL`. You can also run `sudo journalctl -a --since "18 hours ago" | grep -i "killed process` to confirm that the execution client has been killed due to oom. If you are using geth as the execution client, a short term solution is to reduce the resources used, for example: (1) reduce the cache by adding the flag `--cache 2048` (2) connect to less peers using the flag `--maxpeers 10`. If the oom occurs rather frequently, a long term solution is to increase the memory capacity of the computer.
### How do I check or update my withdrawal credentials?
Withdrawals will be available after the Capella/Shanghai upgrades on 12<sup>th</sup> April 2023. To check that if you are eligible for withdrawals, go to [Staking launchpad](https://launchpad.ethereum.org/en/withdrawals), enter your validator index and click `verify on mainnet`:
- `withdrawals enabled` means you will automatically receive withdrawals to the withdrawal address that you set.
- `withdrawals not enabled` means you will need to update your withdrawal credentials from `0x00` type to `0x01` type. The common way to do this is using `Staking deposit CLI` or `ethdo`, with the instructions available [here](https://launchpad.ethereum.org/en/withdrawals#update-your-keys).
For the case of `withdrawals not enabled`, you can update your withdrawal credentials **anytime**, and there is no deadline for that. The catch is that as long as you do not update your withdrawal credentials, your rewards in the beacon chain will continue to be locked in the beacon chain. Only after you update the withdrawal credentials, will the rewards be withdrawn to the withdrawal address.
### I am missing attestations. Why?
The first thing is to ensure both consensus and execution clients are synced with the network. If they are synced, there may still be some issues with the node setup itself that is causing the missed attestations. Check the setup to ensure that:
- the clock is synced
- the computer has sufficient resources and is not overloaded
- the internet is working well
- you have sufficient peers
You can see more information on the [Ethstaker KB](https://ethstaker.gitbook.io/ethstaker-knowledge-base/help/missed-attestations). Once the above points are good, missing attestation should be a rare occurance.
### Sometimes I miss the attestation head vote, resulting in penalty. Is this normal?
In general it is unavoiadable to have some penalties occasionally. This is particularly the case when you are assigned to attest on the first slot of an epoch and if the proposer of that slot releases the block late, then you will get penalised for missing the target and head votes. Your attestation performance does not only depend on your own setup, but also on everyone else's performance.
### My beacon node is stuck at downloading historical block using checkpoing sync. What can I do?
Check the number of peers you are connected to. If you have low peers (less than 50), try to do port forwarding on the port 9000 TCP/UDP to increase peer count.

21
book/src/installation-binaries.md
View File

@ -23,21 +23,24 @@ For details, see [Portability](#portability).
## Usage
Each binary is contained in a `.tar.gz` archive. For this example, lets assume the user needs
a portable `x86_64` binary.
a `x86_64` binary.
### Steps
1. Go to the [Releases](https://github.com/sigp/lighthouse/releases) page and
select the latest release.
1. Download the `lighthouse-${VERSION}-x86_64-unknown-linux-gnu-portable.tar.gz` binary.
1. Extract the archive:
1. `cd Downloads`
1. `tar -xvf lighthouse-${VERSION}-x86_64-unknown-linux-gnu.tar.gz`
1. Download the `lighthouse-${VERSION}-x86_64-unknown-linux-gnu.tar.gz` binary. For example, to obtain the binary file for v4.0.1 (the latest version at the time of writing), a user can run the following commands in a linux terminal:
```bash
cd ~
curl -LO https://github.com/sigp/lighthouse/releases/download/v4.0.1/lighthouse-v4.0.1-x86_64-unknown-linux-gnu.tar.gz
tar -xvf lighthouse-v4.0.1-x86_64-unknown-linux-gnu.tar.gz
```
1. Test the binary with `./lighthouse --version` (it should print the version).
1. (Optional) Move the `lighthouse` binary to a location in your `PATH`, so the `lighthouse` command can be called from anywhere.
- E.g., `cp lighthouse /usr/bin`
1. (Optional) Move the `lighthouse` binary to a location in your `PATH`, so the `lighthouse` command can be called from anywhere. For example, to copy `lighthouse` from the current directory to `usr/bin`, run `sudo cp lighthouse /usr/bin`.
> Windows users will need to execute the commands in Step 3 from PowerShell.
> Windows users will need to execute the commands in Step 2 from PowerShell.
## Portability
@ -64,4 +67,4 @@ WARN CPU seems incompatible with optimized Lighthouse build, advice: If you get
On some VPS providers, the virtualization can make it appear as if CPU features are not available,
even when they are. In this case you might see the warning above, but so long as the client
continues to function it's nothing to worry about.
continues to function, it's nothing to worry about.

45
book/src/installation-source.md
View File

@ -5,8 +5,20 @@ the instructions below, and then proceed to [Building Lighthouse](#build-lightho
## Dependencies
First, **install Rust** using [rustup](https://rustup.rs/). The rustup installer provides an easy way
to update the Rust compiler, and works on all platforms.
First, **install Rust** using [rustup](https://rustup.rs/)：
```bash
curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh
```
The rustup installer provides an easy way to update the Rust compiler, and works on all platforms.
> Tips:
>
> - During installation, when prompted, enter `1` for the default installation.
> - After Rust installation completes, try running `cargo version` . If it cannot
> be found, run `source $HOME/.cargo/env`. After that, running `cargo version` should return the version, for example `cargo 1.68.2`.
> - It's generally advisable to append `source $HOME/.cargo/env` to `~/.bashrc`.
With Rust installed, follow the instructions below to install dependencies relevant to your
operating system.
@ -19,10 +31,17 @@ Install the following packages:
sudo apt install -y git gcc g++ make cmake pkg-config llvm-dev libclang-dev clang protobuf-compiler
```
> Tips:
>
> - If there are difficulties, try updating the package manager with `sudo apt
> update`.
> Note: Lighthouse requires CMake v3.12 or newer, which isn't available in the package repositories
> of Ubuntu 18.04 or earlier. On these distributions CMake can still be installed via PPA:
> [https://apt.kitware.com/](https://apt.kitware.com)
After this, you are ready to [build Lighthouse](#build-lighthouse).
#### macOS
1. Install the [Homebrew][] package manager.
@ -39,10 +58,19 @@ brew install protobuf
[Homebrew]: https://brew.sh/
After this, you are ready to [build Lighthouse](#build-lighthouse).
#### Windows
1. Install [Git](https://git-scm.com/book/en/v2/Getting-Started-Installing-Git).
1. Install [Git](https://git-scm.com/download/win).
1. Install the [Chocolatey](https://chocolatey.org/install) package manager for Windows.
> Tips:
> - Use PowerShell to install. In Windows, search for PowerShell and run as administrator.
> - You must ensure `Get-ExecutionPolicy` is not Restricted. To test this, run `Get-ExecutionPolicy` in PowerShell. If it returns `restricted`, then run `Set-ExecutionPolicy AllSigned`, and then run
```bash
Set-ExecutionPolicy Bypass -Scope Process -Force; [System.Net.ServicePointManager]::SecurityProtocol = [System.Net.ServicePointManager]::SecurityProtocol -bor 3072; iex ((New-Object System.Net.WebClient).DownloadString('https://community.chocolatey.org/install.ps1'))
```
> - To verify that Chocolatey is ready, run `choco` and it should return the version.
1. Install Make, CMake, LLVM and protoc using Chocolatey:
```
@ -67,6 +95,8 @@ should follow the instructions for Ubuntu listed in the [Dependencies (Ubuntu)](
[WSL]: https://docs.microsoft.com/en-us/windows/wsl/about
After this, you are ready to [build Lighthouse](#build-lighthouse).
## Build Lighthouse
Once you have Rust and the build dependencies you're ready to build Lighthouse:
@ -136,7 +166,7 @@ Commonly used features include:
* `spec-minimal`: support for the minimal preset (useful for testing).
Default features (e.g. `slasher-mdbx`) may be opted out of using the `--no-default-features`
argument for `cargo`, which can plumbed in via the `CARGO_INSTALL_EXTRA_FLAGS` environment variable.
argument for `cargo`, which can be plumbed in via the `CARGO_INSTALL_EXTRA_FLAGS` environment variable.
E.g.
```
@ -171,12 +201,11 @@ PROFILE=maxperf make
Lighthouse will be installed to `CARGO_HOME` or `$HOME/.cargo`. This directory
needs to be on your `PATH` before you can run `$ lighthouse`.
See ["Configuring the `PATH` environment variable"
(rust-lang.org)](https://www.rust-lang.org/tools/install) for more information.
See ["Configuring the `PATH` environment variable"](https://www.rust-lang.org/tools/install) for more information.
### Compilation error
Make sure you are running the latest version of Rust. If you have installed Rust using rustup, simply type `rustup update`.
Make sure you are running the latest version of Rust. If you have installed Rust using rustup, simply run `rustup update`.
If you can't install the latest version of Rust you can instead compile using the Minimum Supported
Rust Version (MSRV) which is listed under the `rust-version` key in Lighthouse's
@ -185,7 +214,7 @@ Rust Version (MSRV) which is listed under the `rust-version` key in Lighthouse's
If compilation fails with `(signal: 9, SIGKILL: kill)`, this could mean your machine ran out of
memory during compilation. If you are on a resource-constrained device you can
look into [cross compilation](./cross-compiling.md), or use a [pre-built
binary](./installation-binaries.md).
binary](https://github.com/sigp/lighthouse/releases).
If compilation fails with `error: linking with cc failed: exit code: 1`, try running `cargo clean`.

29
book/src/installation.md
View File

@ -8,24 +8,27 @@ There are three core methods to obtain the Lighthouse application:
- [Docker images](./docker.md).
- [Building from source](./installation-source.md).
Community-maintained additional installation methods:
- [Homebrew package](./homebrew.md).
- Arch Linux AUR packages: [source](https://aur.archlinux.org/packages/lighthouse-ethereum),
[binary](https://aur.archlinux.org/packages/lighthouse-ethereum-bin).
Additionally, there are two extra guides for specific uses:
- [Raspberry Pi 4 guide](./pi.md).
- [Cross-compiling guide for developers](./cross-compiling.md).
## Minimum System Requirements
There are also community-maintained installation methods:
* Dual-core CPU, 2015 or newer
* 8 GB RAM
* 128 GB solid state storage
* 10 Mb/s download, 5 Mb/s upload broadband connection
- [Homebrew package](./homebrew.md).
- Arch Linux AUR packages: [source](https://aur.archlinux.org/packages/lighthouse-ethereum),
[binary](https://aur.archlinux.org/packages/lighthouse-ethereum-bin).
For more information see [System Requirements](./system-requirements.md).
[WSL]: https://docs.microsoft.com/en-us/windows/wsl/about
## Recommended System Requirements
Before [The Merge](https://ethereum.org/en/roadmap/merge/), Lighthouse was able to run on its own with low to mid-range consumer hardware, but would perform best when provided with ample system resources.
After [The Merge](https://ethereum.org/en/roadmap/merge/) on 15<sup>th</sup> September 2022, it is necessary to run Lighthouse together with an execution client ([Nethermind](https://nethermind.io/), [Besu](https://www.hyperledger.org/use/besu), [Erigon](https://github.com/ledgerwatch/erigon), [Geth](https://geth.ethereum.org/)). The following system requirements listed are therefore for running a Lighthouse beacon node combined with an execution client , and a validator client with a modest number of validator keys (less than 100):
* CPU: Quad-core AMD Ryzen, Intel Broadwell, ARMv8 or newer
* Memory: 16 GB RAM or more
* Storage: 2 TB solid state storage
* Network: 100 Mb/s download, 20 Mb/s upload broadband connection

27
book/src/pi.md
View File

@ -12,18 +12,18 @@ desktop) may be convenient.*
### 1. Install Ubuntu
Follow the [Ubuntu Raspberry Pi installation instructions](https://ubuntu.com/download/raspberry-pi).
**A 64-bit version is required** and latest version is recommended (Ubuntu
20.04 LTS was the latest at the time of writing).
Follow the [Ubuntu Raspberry Pi installation instructions](https://ubuntu.com/download/raspberry-pi). **A 64-bit version is required**
A graphical environment is not required in order to use Lighthouse. Only the
terminal and an Internet connection are necessary.
### 2. Install Packages
Install the [Ubuntu Dependencies](installation-source.md#ubuntu).
(I.e., run the `sudo apt install ...` command at that link).
Install the Ubuntu dependencies:
```bash
sudo apt install -y git gcc g++ make cmake pkg-config llvm-dev libclang-dev clang protobuf-compiler
```
> Tips:
>
@ -32,15 +32,18 @@ Install the [Ubuntu Dependencies](installation-source.md#ubuntu).
### 3. Install Rust
Install Rust as per [rustup](https://rustup.rs/). (I.e., run the `curl ... `
command).
Install Rust as per [rustup](https://rustup.rs/):
```bash
curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh
```
> Tips:
>
> - When prompted, enter `1` for the default installation.
> - Try running `cargo version` after Rust installation completes. If it cannot
> be found, run `source $HOME/.cargo/env`.
> - It's generally advised to append `source $HOME/.cargo/env` to `~/.bashrc`.
> - During installation, when prompted, enter `1` for the default installation.
> - After Rust installation completes, try running `cargo version` . If it cannot
> be found, run `source $HOME/.cargo/env`. After that, running `cargo version` should return the version, for example `cargo 1.68.2`.
> - It's generally advisable to append `source $HOME/.cargo/env` to `~/.bashrc`.
### 4. Install Lighthouse

23
book/src/system-requirements.md
View File

@ -1,23 +0,0 @@
# System Requirements
Lighthouse is able to run on most low to mid-range consumer hardware, but will perform best when
provided with ample system resources. The following system requirements are for running a beacon
node and a validator client with a modest number of validator keys (less than 100).
## Minimum
* Dual-core CPU, 2015 or newer
* 8 GB RAM
* 128 GB solid state storage
* 10 Mb/s download, 5 Mb/s upload broadband connection
During smooth network conditions, Lighthouse's database will fit within 15 GB, but in case of a long
period of non-finality, it is **strongly recommended** that at least 128 GB is available.
## Recommended
* Quad-core AMD Ryzen, Intel Broadwell, ARMv8 or newer
* 16 GB RAM
* 256 GB solid state storage
* 100 Mb/s download, 20 Mb/s upload broadband connection