Last Updated: July 3, 2022
Table of Contents
This is Part 3a of a step-by-step guide to setup the ChainSafe Lodestar consensus client on the Ethereum Beacon Chain.
This guide is separated into a series of parts, grouped by related steps to setup a full Lodestar consensus beacon node and validator client from start to finish. The topics are separated as follows:
An Ethereum execution node is required for staking. You can either run a local Ethereum execution (Eth1) node or use a third party node. This guide will provide instructions for running a local Go Ethereum (Geth) node.
OPTIONAL: If you would rather use a third party option then skip this step.
NOTE: Check your available disk space. An Ethereum execution (Eth1) node requires roughly 400GB of space. Even if you have a large SSD there are cases where Ubuntu is reporting only 200GB free. If this applies to you then take a look at Appendix A — Expanding the Logical Volume.
We must install Docker Engine & Docker Compose to run the images on your local machine.
Verify the installation was successful.
Docker Compose should return a non-error stating the version and build.
Clone the latest commit of the Lodestar monorepo from Github into your local.
The docker-compose file requires that a .env
file be present in this directory. The default.env
file provides a template and can be copied. Navigate to the extracted directory and copy the template:
Modify the parameters inside the .env
file. Use the nano text editor.
TESTNET USERS: If you want to use Lodestar in a testnet, change LODESTAR_NETWORK
to the desired network such as LODESTAR_NETWORK=prater
.
Then, press CTRL
+ x
then y
then Enter
to save and exit.
We will now generate a new docker-compose.yml
which defines 4 main services to run a local Lodestar node:
nethermind_docker
| besu_docker
| geth_docker
),beacon_node
prometheus
grafana
using the text editor nano
. Open the editor:
An Ethereum execution node is required for staking. You can either run a local Ethereum execution (Eth1) node or use a third party node. This guide will provide instructions for running a local execution node using either Nethermind, Go-Ethereum (Geth), or Besu within Docker containers using Docker-Compose.
NOTE: Check your available disk space. An Ethereum execution (Eth1) node requires roughly 500GB of space. Even if you have a large SSD there are cases where Ubuntu is reporting only 200GB free. If this applies to you then take a look at Appendix A — Expanding the Logical Volume.
For the next step, please choose only 1 of the following 3 options. Doing more than 1 will create port conflicts:
If you would like to use Nethermind as your Ethereum Execution Client (eth1), copy and paste the following into the file:
NOTE: YAML files are sensitive to indentations. Copy the lines exactly as seen below.
TESTNET USERS: If you are running on the Goerli testnet, make sure to modify the command
configuration of the execution client you plan to use.
**Example of Nethermind on the Goerli Testnet (Line 8):
TESTNET USERS: If you would like to pull the unstable nightly
versions of Lodestar, you can change the image:
parameter on Line 13 from chainsafe/lodestar:latest
to chainsafe/lodestar:next
NOTE: You can also add/change Nethermind CLI Commands to run such as --Network.DiscoveryPort=30303
to change the listening port on command:
line 8.
NOTE: You can also add Lodestar CLI commands to run such as --weakSubjectivitySyncLatest
to fetch a weak subjectivity state (see Quick sync your beacon node) with a --weakSubjectivityCheckpoint
on command:
line 19.
When you're done modifying this file, press CTRL
+ x
to exit and press y
, then name the file docker-compose.yml
and press y
to overwrite the current version. Continue to the next step: (Optional) Quick Sync your Beacon Node.
If you would like to use Besu as your Ethereum Execution Client (eth1), copy and paste the following into the file:
NOTE: YAML files are sensitive to indentations. Copy the lines exactly as seen below.
TESTNET USERS: If you are running on the Goerli testnet, make sure to modify the command
configuration of the execution client you plan to use.
**Example of Besu on the Goerli Testnet (Line 8):
TESTNET USERS: If you would like to pull the unstable nightly
versions of Lodestar, you can change the image:
parameter on Line 13 from chainsafe/lodestar:latest
to chainsafe/lodestar:next
NOTE: You can also add/change Besu CLI Commands to run such as --p2p-port=123
to change the listening port on command:
line 8.
NOTE: You can also add Lodestar CLI commands to run such as --weakSubjectivitySyncLatest
to fetch a weak subjectivity state (see Quick sync your beacon node) with a --weakSubjectivityCheckpoint
on command:
line 19.
When you're done modifying this file, press CTRL
+ x
to exit and press y
, then name the file docker-compose.yml
and press y
to overwrite the current version. Continue to the next step: (Optional) Quick Sync your Beacon Node.
If you would like to use Go-Ethereum (Geth) as your Ethereum Execution Client (eth1), copy and paste the following into the file:
NOTE: YAML files are sensitive to indentations. Copy the lines exactly as seen below.
TESTNET USERS: If you are running on the Goerli testnet, make sure to modify the command
configuration of the execution client you plan to use.
**Example of Geth on the Goerli Testnet (Line 8):
TESTNET USERS: If you would like to pull the unstable nightly
versions of Lodestar, you can change the image:
parameter on Line 13 from chainsafe/lodestar:latest
to chainsafe/lodestar:next
NOTE: You can also add Go Ethereum CLI commands to run such as --port 123
to change the listening port on command:
line 8.
NOTE: You can also add Lodestar CLI commands to run such as --weakSubjectivitySyncLatest
to fetch a weak subjectivity state (see Quick sync your beacon node) with a --weakSubjectivityCheckpoint
on command:
line 19.
When you're done modifying this file, press CTRL
+ x
to exit and press y
, then name the file docker-compose.yml
and press y
to overwrite the current version. Continue to the next step: (Optional) Quick Sync your Beacon Node.
https://<project-id>:<project-secret>@eth2-beacon-mainnet.infura.io
where <project-id>
and <project-secret>
are replaced with a bunch of random letters and numbers.docker-compose.yml
file by using the command:command:
in your docker-compose.yml
file:TESTNET USERS: The URL for a Prater endpoint --weakSubjectivityServerUrl
should end in @eth2-beacon-prater.infura.io
Example of Lodestar Beacon with quick sync (Line 19):
When you're done modifying this file, press CTRL
+ x
to exit and press y
, then name the file docker-compose.yml
and press y
to overwrite the current version.
Depending on which execution node you have chosen, start the geth_docker
| nethermind_docker
| besu_docker
service:
NOTE: Replace the following geth_docker
commands with the name of the Execution Node client you are running.
Nethermind Example: sudo docker-compose up -d nethermind_docker
Besu Example: sudo docker-compose up -d besu_docker
If it has initiated properly, it will download the image and return: Creating geth_docker ... done
Check the logs and ensure it is syncing by using docker logs
.
NOTE: You can follow the output logs live by using the -f
flag with the docker logs
command.
Example:
sudo docker logs -f geth_docker
When verified that everything is working properly, exit the log by pressing CTRL
+ C
.
Your execution (eth1) node is now running on a http server at http://127.0.0.1:8545
. Wait until it is synced and proceed to the next step.
To startup the beacon node, use the following command:
If it has initiated properly, it will download the image and return: Creating lodestar_beacon_node_1 ... done
We can confirm if it is running by using the docker ps
command:
You will see a container running the lodestar_beacon_node_1
.
To see the logs from the container, use the command:
QUICK SYNC USERS: If you used quick sync you may encounter error: Error onSyncAggregate message=finalityHeader not available
when initially starting up. This is NORMAL as your light client server does not have the information it requires yet.
NOTE: You can follow the output logs live by using the -f
flag with the docker logs
command.
Example:
sudo docker logs -f lodestar_beacon_node_1
When verified that everything is working properly, exit the log by pressing CTRL
+ C
.
When your beacon node is fully synced, the logs will display a line similar to the one below.
NOTE: If you used Quick sync your beacon node, follow these instructions. Otherwise, skip to Start Prometheus and Grafana Services for Lodestar.
Once your beacon node has synced, you can remove the weakSubjectivity
CLI commands from your docker-compose.yml
file.
Remove the --weakSubjectivitySyncLatest
and the --weakSubjectivityServerUrl
flags from Line 19. When you're done modifying this file, press CTRL
+ x
to exit and press y
to overwrite and Enter
to save the file with the same name.
Start the local metrics docker container.
If it has initiated properly, it will download the image and return: Creating lodestar_prometheus_1 ... done
and Creating lodestar_grafana_1 ... done
We can confirm if it is running by using the Docker ps
command:
As long as the STATUS is not constantly restarting, they are up and running properly.
To check the metrics, you will need to know the IP address of your node in your network. You can check by using:
Use your internet browser and access the Grafana metrics dashboard at port 3000.
Replace <IPaddress>
with the address returned from the previous command.
Log in to your Grafana dashboard and use the default credentials to change your password:
On your left-hand side menu bar, navigate to Dashboards > Browse.
Select Lodestar for our default Lodestar dashboard.
On the top-left corner of the dashboard, make sure you have selected Lodestar
to pull information about your local Lodestar node.
When your beacon node is fully synced, the dashboard will display: Sync status: Synced
.
OPTIONAL: Skip these following steps and proceed to Final Remarks, Next Steps & Appendix if you are not running a validator.
We will create a keystores folder in our Lodestar directory.
During Part 1: Generating Staking Data, you generated one or many keystore files that stores your validator signing keys. We will now import those keystores into the Lodestar validator client. If you generated your keystores on another device, make sure to copy them on your staking machine first. Keystore files normally starts with keystore-m and ends with .json.
Your keystore should be in a located in a known directory. Make sure to insert your own path for where your keystore files are located. There should not be any keystore-directory
literal.
Configure the Lodestar validator by importing the validator keys.
OPTIONAL: If you created your validator keystores on this local machine, skip this step.
If you generated the validator keystore-m.json
file(s) on a machine other than your Ubuntu server you will need to copy the file(s) over to your Lodestar keystores directory. You can do this using a USB drive (if your server is local) or via secure FTP (SFTP) into your Docker container running the validator.
To mount a USB drive into your server, physically insert your USB drive, then find the path to it.
Look for your USB Drive and confirm the information before proceeding.
You will need the device path before continuing. In this example, the path is /dev/sda1
.
Create a new folder under /media
called usb-stick
then mount your USB drive into it. Ensure you replace <USBDevicePath>
with the specific device path to your USB.
Enter your /media/usb-stick
path and ensure you can see the contents within it.
Locate your validator_keys
folder generated from Part 1 and copy it to your Lodestar keystores directory. Insert the path to your validator_keys
folder into <ValidatorKeysFolderPath>
NOTE: If you have your validator_keys
folder on your USB stick, you can use the following commands instead of the ones above:
The contents inside your validator_keys
folder should be now be visible in your Lodestar keystore directory.
If you have your deposit_data
files within your Lodestar keystore directory, you must delete it or you will encounter errors when starting up the validator client. You should only have your keystore-m.json
files here.
To remove any deposit_data
files, you can use the rm
command.
NOTE: Replace <NameOfDepositDataFile>
with the filename of your deposit_data
JSON file.
Use the ls
command to ensure the deposit_data
JSON file(s) are removed.
Unmount your USB stick.
You can now physically remove the USB key from your local server. Continue at the next step: Configure Lodestar Validator Client.
Configure the Lodestar validator by importing the validator keys.
If you generated the validator keystore-m.json
file(s) on the local Ubuntu staking server you will need to copy the file(s) over to your Lodestar keystores directory. You can do this using the cp
command which follows the standard sudo cp <FileFromDirectoryPath> <ToDirectoryPath>
If you followed Part 1: Generating Staking Data you should be able to find your keystore-m.json
file(s) within your validator_keys
folder.
Example:
If you have your deposit_data
files within your Lodestar keystore directory, you must delete it or you will encounter errors when starting up the validator client. You should only have your keystore-m.json
files here.
To remove any deposit_data
files, you can use the rm
command.
NOTE: Replace <NameOfDepositDataFile>
with the filename of your deposit_data
JSON file.
Use the ls
command to ensure the deposit_data
JSON file(s) are removed.
You will now configure the validator client to import your keystore password. We will make a folder called keystores_password
and a text file containing the keystore password.
Type your keystore password (the password you used to encrypt the .json files).
When you're done creating this file, press CTRL
+ x
to exit and press y
to save.
We will recreate the docker-compose.validator.yml file which configures your Lodestar validator docker instance. These parameters will allow you to run the Lodestar validator client through your machine’s host network and connect to your local Ethereum Consensus (eth2) Lodestar beacon node.
Create a new text file with nano.
NOTE: YAML files are sensitive to indentations. Copy the lines exactly as seen below.
TESTNET USERS: If you would like to pull the unstable nightly versions of the Lodestar validator client, you can change the image:
parameter from chainsafe/lodestar:latest
to chainsafe/lodestar:next
When you're done creating this file, press CTRL
+ x
to exit and press y
, then name the file docker-compose.validator.yml
and press y
to overwrite the current version.
To start the validator client, ensure you are in your Lodestar directory in the command line terminal:
Once it successfully builds the validator client container you will see the return ... done
on your new Docker container containing your validator!
Check that all containers are working properly.
If one of the containers continuously reboot, there is an issue and you will need to diagnose them from their logs. You can access these logs with docker logs
NOTE: If you see this within your validator's logs:
info: Node is syncing - Error on getProposerDuties - Service Unavailable: Node is syncing
This is normal if your beacon node has not fully synced to the head of the network yet.
You can also check that you validators are connected through your Grafana dashboard under "Validators connected".
Rebooting your server should autostart all of the containers. Check by rebooting your server, then checking the docker processes.
You should now have a functioning Ubuntu based staking server set up with Docker containers.
Continue on with the guide to fund your validator keys in Part 4: Funding Your Validator Keys.