# Lodestar Setup Guide on Ethereum Beacon Chain (Ubuntu 20.04.3 + Docker Compose) :::warning :heavy_exclamation_mark: This guide has been deprecated. The updated Lodestar Setup Guide v2 is located here: https://hackmd.io/@philknows/rk5cDvKmK ::: **Last Updated:** September 20, 2021 **Table of Contents** [toc] --- This is a step-by-step guide to setup the ChainSafe Lodestar consensus client for Ethereum. This is an adaptation of [Somer Esat's guides](https://someresat.medium.com/) and [CoinCashew's Security Guide](https://www.coincashew.com/coins/overview-eth/guide-or-security-best-practices-for-a-eth2-validator-beaconchain-node) specifically for Lodestar users and testers. It is based on the following technologies: - [Ubuntu v20.04.3 (LTS) x64 server](https://ubuntu.com/download/server) - [Go-Ethereum Execution Node (Geth)](https://geth.ethereum.org/) | [Github](https://github.com/ethereum/go-ethereum/releases/) - [ChainSafe's Lodestar Ethereum Consensus Client](https://lodestar.chainsafe.io/) | [Github](https://chainsafe.github.io/lodestar/) - [Docker Engine](https://docs.docker.com/engine/) and [Docker Compose](https://docs.docker.com/compose/) - [MetaMask Crypto Wallet & Browser Extension](https://metamask.io/download.html) --- :::danger :warning: **WARNING:** Staking requires at least 32 ETH + gas fees. **DO NOT** send ETH anywhere without knowing what you are doing. This guide includes instructions to safely deposit your ETH for staking on the Ethereum Beacon Chain (testnets and mainnet) using official methods. Never send your ETH to anyone. ::: :::warning :mega: **DISCLAIMER:** This article (the guide) is for informational purposes only and does not constitute professional advice. The author does not guarantee accuracy of the information in this article and the author is not responsible for any damages or losses incurred by following this article. A full disclaimer can be found at the bottom of this page — please read before continuing. ::: --- ## Support For technical support please reach out to: - The Lodestar team actively develops and collaborates on the [ChainSafe Discord Server](https://discord.gg/642wB3XC3Q) under ***#:star2:-lodestar-general*** channel ## Prerequisites This guide assumes knowledge of Ethereum, ETH, Docker, staking, Linux, and MetaMask (or Portis or Fortmatic). This guide also requires the following before getting started: - [Ubuntu server v20.04.3 (LTS) amd64](https://ubuntu.com/download/server) or newer, installed and running on a local computer or in the cloud. *A locally running computer is encouraged for greater decentralization — if the cloud provider goes down then all nodes hosted with that provider go down.* - [MetaMask crypto wallet browser extension](https://metamask.io/download.html) (or Portis or Fortmatic), installed and configured. A computer with a desktop (Mac, Windows, Linux, etc.) and a browser (Brave, Safari, FireFox, etc.) is required. ## Testnet to Mainnet If moving from a testnet setup to a mainnet setup it is strongly recommended that you start on fresh (newly installed) server instance. This guide has not been tested for migration scenarios and does not guarantee success if you are using an existing instance with previously installed testnet software. ## Hardware Requirements ```csvpreview {header="true"} ,Minimum,Recommended Processor,Intel Core i5–760 or AMD FX-8100,Intel Core i7–4770 or AMD FX-8310 Memory,4GB RAM,8GB+ RAM Storage,20GB available space SSD,100GB+ available space SSD Internet,Broadband connection,Broadband connection ``` :::info **NOTE:** Check your available disk space. Even 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 C — Expanding the Logical Volume.*** ::: --- # Overview This guide will cover the following topics: - Generate the staking *validator keys* and *deposit data* - Prepare the Ubuntu Server (firewall, security, etc.) - Set up the Go-Ethereum Execution Node (Geth) and sync it with the selected blockchain (testnet or mainnet) - Install the Lodestar client with Docker Compose, ~~configure it to sync with Geth and continuously update to the latest image via Watchtower~~ (Coming Soon)(tm) - ~~Auto-start containers after reboot~~ (Coming Soon)(tm) - Deposit ETH to activate validator keys **Let's get started!** --- ## Step 1: Generate Staking Data In order to participate in staking it is necessary to generate some data files based on the number of validators you’d like to fund and operate. > **OPTIONAL:** If you have already generated your deposit data and validator key(s) you can skip this step. Each validator requires a deposit of 32 ETH. You should have sufficient ETH in your MetaMask wallet to fund each validator. For example if you plan to run 5 validators you will need to have (32 x 5) = 160 ETH plus some extra to cover the gas fees. The ETH deposit will happen later in the guide after everything else is up and running. :::warning **TESTNET USERS:** If you are running Lodestar on a testnet, you will need testnet ETH to complete your setup. You can obtain it from the following sources: **Goerli Testnet Faucets** https://faucet.goerli.mudit.blog/ https://goerli-faucet.slock.it/ ::: ### Download the eth2.0-deposit-cli Go [here](https://github.com/ethereum/eth2.0-deposit-cli/releases/) to get the “Latest release” of the deposit command line interface (CLI) app. ![](https://i.imgur.com/wT4PtQa.png) In the assets section download the version matching the platform you are currently on (e.g. Windows, Mac, Linux Desktop, etc.). ### Run the eth2.0-deposit-cli Decompress the archive. There should be a binary file (executable) inside. The deposit tool generates files for staking as well as a mnemonic key. This key must be handled securely. There are two options to proceed from here. **Recommended** — Copy the binary file to a USB drive. Connect to a fully air-gapped machine (never previously connected to the internet), copy the file over and run from there. **Not recommended** — Run from the current machine. An internet connection may be an opportunity to leak your mnemonic key. If a fully air-gapped machine isn’t available disconnect the internet on the current machine before proceeding. When ready, run the file in a terminal window (or CMD in Windows) to continue using the commands below: - Replace `<NumberOfValidators>` with the number of validators you want to fund. E.g. `--num_validators 2`. - Replace `<ChainID>` with the network you intend to use. E.g. `--chain mainnet` or `--chain prater` *On Linux/Mac:* ``` ./deposit new-mnemonic --num_validators <NumberOfValidators> --chain <ChainID> ``` *On Windows* ``` deposit.exe new-mnemonic --num_validators <NumberOfValidators> --chain <ChainID> ``` Once you execute the above steps on your platform of choice you will be asked to create a **validator keystore** password. **Back it up somewhere safe.** You will need this later to load the validator keys into the Lodestar validator client. ![](https://i.imgur.com/WKlrVUI.png) <br/> :::danger **WARNING:** A seed phrase (**mnemonic**) will be generated. ++**Back it up somewhere safe. This is CRITICAL.**++ You will eventually use this to generate your withdrawal keys for your ETH or add additional validators. If you lose this key you will not be able to withdraw your funds. If this key is compromised by somebody else, they will be able to withdraw your funds. ::: ![](https://i.imgur.com/3fRAa1f.png) :::danger **WARNING:** Do not use the 24 word example above. Once a 24 word phrase is made public, it is compromised. ::: Once you have confirmed your mnemonic your validator keys will be created. ![](https://i.imgur.com/wOkD1Yl.png) <br/> The newly created validator keys and deposit data file are created at the specified location. The contents of the folder are shown below. ![](https://i.imgur.com/1Yq3aZl.png) - The `deposit_data-[timestamp].json` file contains the public keys for the validators and information about the staking deposit. This file will be used to complete the ETH deposit process later on. - The `keystore-m...json` files contain the encrypted validator signing key. There is one keystore-m per validator that you are funding. These will be imported into the Lodestar validator client for use while staking. You will copy these files over to the Ubuntu server (if not already there) later. ### Final Steps Now that you have the deposit data and the keystore files move on to set up the Ubuntu server. **DO NOT DEPOSIT any ETH at this moment.** It is important to complete and verify your staking setup first. If the ETH deposits become active and your staking setup is not ready you will start receiving penalties for non-activity. --- ## Step 2: Connect to the Server Using a SSH client, connect to your Ubuntu server. If you are logged in as `root` then create a user-level account with admin privileges instead, since logging in as the root user is *++risky++*. :::info **NOTE:** If you are not logged in as root then skip this and go to Step 3. ::: Create a new user. Replace `<yourusername>` with a username of your choice. You will asked to create a strong password and provide some other optional information. ``` adduser <yourusername> ``` Grant admin rights to the new user by adding it to the `sudo` group. This will allow the user to perform actions with superuser privileges by typing `sudo` before commands. ``` usermod -aG sudo <yourusername> ``` *Optional:* If you used SSH keys to connect to your Ubuntu instance via the `root` user you will need to associate the new user with the root user’s SSH key data. ``` rsync --archive --chown=<yourusername>:<yourusername> ~/.ssh /home/<yourusername> ``` Finally, log out of `root` and log in as `<yourusername>`. --- ## Step 3: Update the Server Make sure the system is up to date with the latest software and security updates. ``` sudo apt update && sudo apt upgrade sudo apt dist-upgrade && sudo apt autoremove sudo reboot ``` --- ## Step 4: Secure the Server Security is important. This is not a comprehensive security guide, just some basic settings. ### Modify the Default SSH Port Port 22 is the default SSH port and a common attack vector. Change the SSH port to avoid this. Choose a port number between 1024–49151 and run the following command and replace `<YourSSHPortNumber>` with the selected port number to check that it is not already in use: ``` sudo ss -tulpn | grep ':<YourSSHPortNumber>' ``` A blank response indicates not in use, a red text response indicates it is in use: try a different port. E.g. `sudo ss -tulpn | grep ':6673'` If confirmed available, modify the default port by updating SSH config. ``` sudo nano /etc/ssh/sshd_config ``` ![](https://i.imgur.com/IynHQrO.png) <br/> Find or add (if not present) the line `Port 22` in the file. Remove the # (if present) and change the value as below. ``` Port <YourSSHPortNumber> ``` Check the screen shot below for reference of `Port 123` as an example. Press CTRL+x then ‘y’ then ‘Enter’ to save and exit. ![](https://i.imgur.com/uu46IVu.png) <br/> Restart the SSH service to reflect the above changes. ``` sudo systemctl restart ssh ``` Log out and log back in via SSH using `<YourSSHPortNumber>` for the port. ### Setup 2-Factor Authentication for your Server > **OPTIONAL:** If you would like added security on top of your password, you can setup Google Authenticator to further protect your server from unauthorized access. Otherwise, skip this section and continue to Configure the Firewall. Install the package required for Google Authenticator. ``` sudo apt install libpam-google-authenticator -y ``` To make SSH use the Google Authenticator PAM module, you will need to edit the file located in `/etc/pam.d/sshd`: ``` sudo nano /etc/pam.d/sshd ``` In the configuration file, add the following line at the bottom of the file: ``` auth required pam_google_authenticator.so ``` Check the screen shot below for reference. Press CTRL+x then ‘y’ then ‘Enter’ to save and exit. ![](https://i.imgur.com/DihQJyD.png) <br/> Now we will restart the `sshd` daemon with the following command: ``` sudo systemctl restart sshd.service ``` We must now modify the `sshd` configuration file located at `/etc/ssh/sshd_config`: ``` sudo nano /etc/ssh/sshd_config ``` We will locate the following parameters and update it to `yes`. Check the screen shot below for reference. ``` ChallengeReponseAuthentication yes UsePAM yes ``` ![](https://i.imgur.com/R3dTdl3.png) </br> Press CTRL+x then ‘y’ then ‘Enter’ to save and exit. We will now setup Google Authenticator with the following command: ``` google-authenticator ``` You will be asked a series of questions and the recommendated settings are: - Make tokens “time-base”": yes - Update the .google_authenticator file: yes - Disallow multiple uses: yes - Increase the original generation time limit: no - Enable rate-limiting: yes Use the screenshots below as an example reference: ![](https://i.imgur.com/Oh1glHz.png) ![](https://i.imgur.com/TjPgcXR.png) <br/> :::danger The giant QR code that appeared is a representation of your secret key used for your Google Authenticator application. This key is required to generate the proper 6 digit codes you use to verify your 2FA and log into your server. It is ++**VERY IMPORTANT**++ to write down your emergency scratch codes and ++**KEEP THEM SAFE**++ incase you lose access to your phone. ::: Now open Google Authenticator on your phone and add your secret key to make sure you have access to your server after inputting your password. ### Configure the Firewall Ubuntu 20.04 servers can use the default UFW firewall to restrict inbound traffic to the server. Before you enable it allow inbound traffic for SSH, Go Ethereum, and Lodestar. #### Install UFW UFW should be installed by default. The following command will ensure it is. ``` sudo apt install ufw ``` #### Apply UFW Defaults Explicitly apply the defaults. Inbound traffic denied, outbound traffic allowed. ``` sudo ufw default deny incoming sudo ufw default allow outgoing ``` #### Allow SSH Allow inbound traffic on `<YourSSHPortNumber>` as set above. SSH requires the TCP protocol. E.g. `sudo ufw allow 123/tcp` ``` sudo ufw allow <YourSSHPortNumber>/tcp ``` #### Deny SSH Port 22 Deny inbound traffic on Port 22/TCP. :::info Only do this after you SSH in using `<YourSSHPortNumber>`. ::: ``` sudo ufw deny 22/tcp ``` #### Allow Go Ethereum (Geth) Allow P2P connections with Go Ethereum peers on Port 30303. > **OPTIONAL** If using an Ethereum Execution Node hosted by a [3rd party](https://ethereumnodes.com/), skip this step. :::info **NOTE:** If you are hosting your Ubuntu instance locally, your internet router may need to be ++[configured](https://www.howtogeek.com/66214/how-to-forward-ports-on-your-router/)++ to allow and forward incoming traffic on port 30303 to your server. ::: ``` sudo ufw allow 30303 ``` #### Allow Lodestar Ports Allows P2P connections with Lodestar peers for actions on the beacon node (Port 9000) :::info **NOTE:** If you are hosting your Ubuntu instance locally, your internet router may need to be ++[configured](https://www.howtogeek.com/66214/how-to-forward-ports-on-your-router/)++ to allow and forward incoming traffic on port 9000 to your server. ::: ``` sudo ufw allow 9000 ``` Allow HTTP connections to Prometheus metrics (Port 3000) ``` sudo ufw allow 3000 ``` #### Enable the Firewall Enable the firewall and verify the rules have been correctly configured ``` sudo ufw enable sudo ufw status numbered ``` Check the screenshot below for reference. ![](https://i.imgur.com/tofIANl.png) --- ## Step 5: Configure Timekeeping on the Server Ubuntu has time synchronization built in and activated by default using systemd’s timesyncd service. Verify it’s running correctly. ``` timedatectl ``` The `NTP service` should be `active`. If not then run: ``` sudo timedatectl set-ntp on ``` Check the screenshot below for reference: ![](https://i.imgur.com/MR1MF31.png) <br/> You should only be using a single keeping service. If you were using NTPD from a previous installation you can check if it exists and remove it using the following commands. ``` ntpq -p sudo apt-get remove ntp ``` --- ## Step 6: Setup a local Go-Ethereum Execution (Geth) Node An Ethereum execution node is required for staking. You can either run a local Ethereum execution (Eth1) node or use a [third party node](https://ethereumnodes.com). This guide will provide instructions for running a local [Go Ethereum (Geth)](https://geth.ethereum.org/) node. > **OPTIONAL:** If you would rather use a third party option then skip this step. Instructions will be provided to setup a third party option in Step 9 when configuring the Beacon Node Service. :::info **NOTE:** Check your available disk space. An Ethereum execution (Eth1) node requires roughly 400GB of space. Even 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 C — Expanding the Logical Volume***. ::: ### Install Go Ethereum (Geth) Install the Go Ethereum client using PPA’s (Personal Package Archives). ``` sudo add-apt-repository -y ppa:ethereum/ethereum sudo apt update sudo apt install geth ``` Go Ethereum will be configured to run as a background service. Create an account for the service to run under. This type of account can’t log into the server. ``` sudo useradd --no-create-home --shell /bin/false goeth ``` Create the data directory for the Ethereum execution chain (Eth1). This is required for storing the execution (Eth1) node data. ``` sudo mkdir -p /var/lib/goethereum ``` Set directory permissions. The `goeth` account needs permission to modify the data directory. ``` sudo chown -R goeth:goeth /var/lib/goethereum ``` Create a systemd service config file to configure the service. ``` sudo nano /etc/systemd/system/geth.service ``` Paste the following service configuration into the file. ``` [Unit] Description=Go Ethereum Client After=network.target Wants=network.target [Service] User=goeth Group=goeth Type=simple Restart=always RestartSec=5 ExecStart=geth --http --datadir /var/lib/goethereum --cache 2048 --maxpeers 30 [Install] WantedBy=default.target ``` :::warning **TESTNET USERS:** If you are running your Lodestar client on a **testnet**, you will need to connect your Ethereum execution node to an Ethereum execution testnet such as Goerli. Any custom configurations/flags for your Go Ethereum node can be added/modified in the `ExecStart=geth` line with custom command line flags. To connect your Geth node to Goerli, you can add the flag `--goerli` to the `ExecStart=geth` line: <br/> **Example:** `ExecStart=geth --goerli --http --datadir /var/lib/goethereum --cache 2048 --maxpeers 30` ::: | [Notable Flags](https://geth.ethereum.org/docs/interface/command-line-options) | Description | | -------- | -------- | `--http` | Expose an HTTP endpoint (http://localhost:8545) that the Lodestar beacon chain will connect to. `--cache` | Size of the internal cache in GB. Reduce or increase depending on your available system memory. A setting of 2048 results in roughly 4–5GB of memory usage. `--maxpeers` | Maximum number of peers to connect with. More peers equals more internet data usage. Do not set this too low or your Geth node will struggle to stay in sync. <br/> Check the screen shot below for reference. Press CTRL+x then ‘y’ then ‘Enter’ to save and exit. ![](https://i.imgur.com/2v8QYOr.png) ***Mainnet Reference*** <br/> ![](https://i.imgur.com/Tc1ENNV.png) ***Goerli Testnet Reference*** Reload systemd to reflect the changes and start the service. Check status to make sure it’s running correctly. ``` sudo systemctl daemon-reload sudo systemctl start geth sudo systemctl status geth ``` Check the screen shot below for reference. ![](https://i.imgur.com/XbBlvah.png) It should say **active (running)** in **green bold text**. If not then go back and repeat the steps to fix the problem. Press Q to quit (will not affect the geth service). Enable the geth service to automatically start on reboot. ``` sudo systemctl enable geth ``` The Go Ethereum node will begin to sync. You can follow the progress or check for errors by running the following command. Press CTRL+c to exit (will not affect the geth service). ``` sudo journalctl -fu geth.service ``` ### Check Sync Status To check your Geth node sync status use the following command to access the console. ``` geth attach > eth.syncing ``` If `false` is returned then your sync is complete. If syncing data is returned then you are still syncing. Press CTRL+d to exit when done. ### Check Connected Peers To check your Geth node connected peers use the following command to access the console. ``` geth attach > net.peerCount ``` The `peerCount` will not exceed your setting for `--maxpeers`. If you are having trouble finding peers to sync see the next section. Press CTRL+d to exit when done. ### *Optional:* Add Bootnodes Sometimes it can take a while to find peers to sync. If so, you can add some bootnodes to help things along. Click below for the latest peers list: [**Mainnet Peers List**](https://gist.github.com/rfikki/a2ccdc1a31ff24884106da7b9e6a7453) [**Goerli Peers List**](https://gist.github.com/rfikki/77081600ddc8432520d3bb3a9f80a493) Modify the geth service as follows: ``` sudo systemctl stop geth sudo nano /etc/systemd/system/geth.service ``` Modify the `ExecStart` line and add the `--bootnodes` flag with a few of the latest peers, comma separated. Below is an example: ``` ExecStart=geth --http --datadir /var/lib/goethereum --cache 2048 --maxpeers 30 --bootnodes "enode://d0b4a09d072b3f021e233fe55d43dc404a77eeaed32da9860cc72a5523c90d31ef9fab7f3da87967bc52c1118ca3241c0eced50290a87e0a91a271b5fac8d0a6@,enode://5070366042daaf15752fea340e7ffce3fd8fc576ac846034bd551c3eebac76db122a73fe8418804c5070a5e6d690fae133d9953f85d7aa00375d9a4a06741dbc@" ``` Save the file and exit. Restart the service and observe. ``` sudo systemctl daemon-reload sudo systemctl start geth sudo journalctl -fu geth.service ``` :::info **NOTE:** It is necessary to follow a specific series of steps to update Geth. ***See Appendix A — Updating Geth for further information.*** ::: --- ## Step 7: Setup Dependencies, Docker and Docker Compose ### Install Python To ensure you have the proper dependencies, install Python with the command: ``` sudo apt install python ``` ### Install Node Version Manager (NVM) and NodeJS Use the following command to download and initiate the NVM install. ``` cd ~ curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.38.0/install.sh | bash ``` ![](https://i.imgur.com/TOgZ8wH.png) </br> Once it is complete, close your terminal session and re-open a terminal session with your server. Use `nvm` to install the latest version of [NodeJS](https://nodejs.org/en/) using the command: ``` nvm install node ``` ![](https://i.imgur.com/hf5NjAR.png) Verify your installation of node by using the command: ``` node --version ``` Node.js should return the current version of your Node installation. ### Install Yarn Install Yarn via npm package manager: ``` npm install --global yarn ``` Once installed, you can check that Yarn is installed by using the command: ``` yarn --version ``` ![](https://i.imgur.com/fpKiOmn.png) It should return a non-error message with the current `x.xx.xx` version of Yarn. ### Install Docker Install Docker using Snapcraft: ``` sudo snap install docker ``` Ensure Docker is properly setup by using the following command: ``` docker -v ``` It should return a non-error message with the current `Docker version XX.XX.X. build xxxxxx` installed. ![](https://i.imgur.com/EZdaIE8.png) ### Install Docker Compose First, we must confirm the latest release on the [Docker Compose Github Release Page](https://github.com/docker/compose/releases). At the time of this writing, the latest release is version `1.29.2` To download the latest release, use the following command and replace `1.29.2` with the latest version: ``` sudo curl -L "https://github.com/docker/compose/releases/download/1.29.2/docker-compose-$(uname -s)-$(uname -m)" -o /usr/local/bin/docker-compose ``` Change the permissions to allow docker-compose to be executable. ``` sudo chmod +x /usr/local/bin/docker-compose ``` Verify the installation was successful. ``` docker-compose --version ``` Docker Compose should return a non-error stating the version and build. ![](https://i.imgur.com/3IHYtw8.png) --- ## Step 8: Download and Configure Lodestar Environment Go to the [Lodestar Releases webpage](https://github.com/ChainSafe/lodestar/releases) and identify the latest release. It is at the top of the page. For example: ![](https://i.imgur.com/l9J5oXJ.png) In the **assets** section, copy the download link to the **.tar.gz** file by right clicking **Source code** (tar.gz), and then **Copy Link Address**. Download the source code using the commands below. :::info **NOTE:** Example commands below are based on `v0.30.0` of Lodestar. Modify the URLs, folder names and commands accordingly to the release version you have downloaded. ::: ``` cd ~ sudo apt install curl curl -LO https://github.com/ChainSafe/lodestar/archive/refs/tags/v0.30.0.tar.gz ``` Extract the source code from the archive. ``` tar xvf v0.30.0.tar.gz ``` ### Setup the environment 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: ``` cd lodestar-v0.30.0 cp default.env .env ``` Modify the parameters inside the `.env` file. Use the nano text editor. ``` nano .env ``` :::warning **TESTNET USERS:** If you want to use Lodestar in a testnet, change `LODESTAR_NETWORK` to the desired network such as `LODESTAR_NETWORK=prater`. ::: On the `GF_SECURITY_ADMIN_PASSWORD` line, input a password to access your Graphana metrics dashboard. **Remember this password as you will require it to check your metrics dashboard in Step 12.** Then, press CTRL+x then ‘y’ then ‘Enter’ to save and exit. ![](https://i.imgur.com/tL9jV89.png) ### Install and build the packages Ensure you have the build dependencies: ``` sudo apt install make && sudo apt install build-essential ``` Install the packages by using: ``` yarn install --ignore-optional ``` :::info **NOTE:** Using the `--ignore-optional` flag prevents downloading the eth2 spec tests. ::: Then build across all packages by using: ``` yarn run build ``` You can verify that Lodestar is ready for use by using the commands: ``` ./lodestar --help ``` You should see a list of commands and information about your current version. ![](https://i.imgur.com/1wdg6oH.png) Clean up the files from your system. ``` cd ~ sudo rm v0.30.0.tar.gz ``` --- ## Step 9: Copy the Validator Keys to your local server Configure the Lodestar validator by importing the validator keys. > **OPTIONAL:** If you created your validator keystores on this local machine, skip this step and proceed to Step 10. 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 home 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. ``` sudo fdisk -l ``` Look for your USB Drive and confirm the information before proceeding. ![](https://i.imgur.com/HdyXS6D.png) 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. ``` sudo mkdir /media/usb-stick sudo mount <USBDevicePath> /media/usb-stick ``` Enter your `/media/usb-stick` path and ensure you can see the contents within it. ``` cd /media/usb-stick ls ``` Locate your `validator_keys` folder generated from Step 1 and copy it to your home user directory. Insert the path to your `validator_keys` folder into `<ValidatorKeysFolderPath>` ``` sudo cp -r <ValidatorKeysFolderPath> ~/ cd ~ ls ``` Your `validator_keys` folder should be visible in your home user directory. ![](https://i.imgur.com/F3X8Oll.png) Unmount your USB stick. ``` sudo umount <USBDevicePath> ``` You can now physically remove the USB key from your local server. --- ## Step 10: Import the Keystore Files into your Validator client You will now need to run the Lodestar Validator import process to add your validator keys to the Docker container. Navigate back to your Lodestar folder. ``` cd ~/lodestar-0.30.0 ``` :::info **NOTE:** You must specifically modify the following command based on the location of your `validator_keys` folder how you want to configure Lodestar. `--directory` identifies where your `validator_keys` folder is located. Replace `<PathToValidatorKeys>` with the path to your `validator_keys` directory. ::: :::warning **TESTNET USERS:** `--network` identifies which network you want to associate your validator key with. Replace with `prater` or `pyrmont` as necessary. ::: ``` ./lodestar account validator import --network mainnet --directory <PathToValidatorKeys> --keystoresDir ./keystores/ --secretsDir ./secrets ``` ![](https://i.imgur.com/RDyQvWE.jpg) Type in your password. If correct, you will receive a `Successfully imported validator <PublicKey>`. --- ## Step 11: Configure the Beacon Node, Validator and Metric Containers In this step, users can customize settings for the Lodestar beacon node, validator and metrics in Docker containers. The settings are already configured for an optimal setup, however advanced users may modify the configuration for their needs. > **OPTIONAL**: This step is currently optional and recommended only for advanced users who need to customize parameters in the beacon node, validator or metric containers. | Notable Files | Description | | -------- | -------- | `docker-compose.yml` | Contains configurations to the beacon node and metrics containers. `docker-compose.validator.yml` | Contains configurations specifically to the validator client. `DockerFile` | Instructions to build the docker containers. You can find a list of customizable flags for Lodestar in our documentation [here](https://chainsafe.github.io/lodestar/reference/cli/). :::info **NOTE:** In the near future, this guide will modify Lodestar to use our host machine's network so that we can configure Lodestar's beacon to use our local Geth node as an eth1 endpoint. Stay tuned! ::: :::warning **KNOWN ISSUE:** As of v0.30.0, the eth1 endpoint is defaulted to an Infura endpoint for rapid testing and will not require a custom endpoint at this time. It will be defaulted back to `http://localhost:8545` in the near future. ::: --- ## Step 12: Run the Beacon Node + Metrics Docker Container To start the docker containers, ensure you are in the correct directory. ``` cd ~/lodestar-0.30.0 ``` Use the following command(s) to start the container(s). To start the beacon node with metrics only: ``` sudo docker-compose up -d ``` :::warning **KNOWN ISSUE:** As of v0.30.0, Docker Compose is creating `FileNotFoundError` errors which lead to `Failed to execute script docker-compose` during the build. If you experience this, you can re-run the same `sudo docker-compose up -d` command above to restart the process. The 3rd retry will lead to it successfully building. We're working to fix this. ![](https://i.imgur.com/k1bNyMy.png) ::: Once it successfully builds the containers you will see the returns `... done` on your new Docker containers containing your Lodestar setup! ![](https://i.imgur.com/k7LSfhH.png) ### Verifying your Beacon Node Ensure your beacon node container is running properly. ``` sudo docker ps ``` Docker should return a list of your running containers. Your container ID will vary. ![](https://i.imgur.com/EiMxsxl.png) Take note of the container ID which runs the `lodestar-0300_beacon_node_1`. Use the following command to follow the logs of the beacon node to ensure it is connected, found peers and syncing. Replace `ContainerID` with the first 3 letters/numbers of the container you are targetting (in this example the `<ContainerID>` is `d67`): ``` sudo docker logs -f <ContainerID> ``` If the beacon node is running correctly, you will see the beacon node syncing via the logs. ![](https://i.imgur.com/z7JfuW1.png) Press CTRL+c to exit. ### Verifying your Metrics Ensure your metrics container is running Graphana and Prometheus properly. Find your host IP address. If the local server is in your home network, it will usually begin with `192.168.xxx.xxx` Use the command below to find your host IP address: ``` hostname -I ``` ![](https://i.imgur.com/sPxEOlP.png) In this example, the host IP address is ``. To access metrics on your web browser, append `:3000` to the end of the host IP address. Example: `` Log in with the username `admin` and the password you set in Step 8. ![](https://i.imgur.com/a1SzNmt.png) Use the navigation in the top-left corner and click on "General". Then navigate to the "Lodestar" folder to get metrics from your Docker containers. --- ## Step 13: Run the Validator client Docker Container > **OPTIONAL:** Skip this step if you are not running a validator. To start the validator client, go back to your Lodestar directory in the command line terminal: ``` cd ~/lodestar-0.30.0 sudo docker-compose -f docker-compose.yml -f docker-compose.validator.yml up -d --no-recreate --remove-orphans ``` Once it successfully builds the validator client container you will see the return `... done` on your new Docker container containing your validator! ### Verifying your Validator Ensure your validator client is running. ``` sudo docker ps ``` Docker should return a list of your running containers. Your container ID will vary. ![](https://i.imgur.com/871XYi2.png) Take note of the container ID which runs the `lodestar-0300_validator_1`. Use the following command to follow the logs of the validator client to ensure it is connected and awaiting beacon node sync. Replace `<ContainerID>` with the first 3 letters/numbers of the container you are targetting (in this example the `<ContainerID>` is `63d`): ``` sudo docker logs -f <ContainerID> ``` If the validator is running correctly, you will see the validator client detects your validator keystores and return errors on `getProposerDuties` as the beacon node syncs. ![](https://i.imgur.com/Jt7RvKU.png) Press CTRL+c to exit. --- ## Step 14: Fund the Validator Keys Now that your set up is up and running, you will need to deposit ETH to fund your validators. :::info **NOTE:** If you have already submitted your staking deposits you can skip this step. ::: This step involves depositing the required amount of ETH to the Eth2.0 deposit contract. **DO NOT SEND ETH TO THE DEPOSIT CONTRACT DIRECTLY!** This process will be done in a web browser running your MetaMask (or other) wallet via the Eth2.0 Launchpad website. :::info **NOTE:** It is recommended that your Geth node and beacon chain have fully synced before proceeding with the deposit. If you don't, Lodestar will be inactive while either nodes sync and you may be subject to inactivity penalties. ::: Go here for Mainnet users: https://launchpad.ethereum.org/ :::warning **TESTNET USERS:** Go here for Prater testnet users: https://prater.launchpad.ethereum.org/ ::: Click through the warning steps and continue through the screens until you get to the **Generate Key Pairs** section. Select the number of validators you are going to run. Choose a value that matches the number of validator files you generated in Step 1. ![](https://i.imgur.com/GALudY3.png) You will be asked to upload the `deposit_data-[timestamp].json` file. You generated this file in Step 1. Browse/select or drag the file and click Continue. ![](https://i.imgur.com/VwC0YDB.png) Connect your wallet. Choose MetaMask (or one of the other supported wallets), log in, select the account where you have your ETH and click Continue. Your MetaMask balance will be displayed. The site will allow you to continue if you have selected Mainnet and you have sufficient ETH balance. ![](https://i.imgur.com/kxaJyTc.png) A summary shows the number of validators and total amount of ETH required. Tick the boxes if you agree and click continue. ![](https://i.imgur.com/whTX1aA.png) If you are ready to deposit click on Confirm deposit. ![](https://i.imgur.com/KMTHvAL.png) This will pop open MetaMask (or other wallet) where you can confirm each transaction. Once all the transactions have successfully completed you are done! ![](https://i.imgur.com/3L8OQPa.png) Congratulations you have deposited your stake! ### Check the Status of your Validator Deposits Newly added validators can take a while (hours to days) to activate. You can check the status of your keys with these steps: 1. Copy your MetaMask (or other) wallet address. 2. Go here: beaconcha.in/ 3. Search for your key(s) using your wallet address. Diving into a specific validator you see a Status that provides an estimate until activation for each validator. ![](https://i.imgur.com/juR0Ih2.png) You now have a functioning beacon chain and validator and your mainnet/testnet deposit is in. Once your deposit is active and the Ethereum 2.0 mainnet is running you will begin staking and earning rewards. ## Final Remarks and Recommend Next Steps Thank you for reading this guide. Remember that Lodestar is still experimental software and this guide will be updated to include changes to any processes or software configurations. At this current time, not all goals of the guide have been implemented. These features are upcoming and will be implemented after further testing: - Auto-start docker containers during boot - Use the local geth node as an eth1 endpoint. - Use watchtower to auto-update to the latest Lodestar release. **Next Steps** - Triple check all key and password backups. - Understand how to update the client and server software. - Use htop to monitor resources on the local machine. - Get familiar with [beaconcha.in](https://beaconcha.in) so you can monitor your validators. They offer alerting (via email — sign up required) and [monitoring](https://kb.beaconcha.in/beaconcha.in-explorer/mobile-app-less-than-greater-than-beacon-node). - Join the [Ethstaker](https://reddit.com/r/ethstaker) and [ChainSafe](https://discord.gg/642wB3XC3Q) Discord for important notifications. - Share any feedback for this guide on [Discord](https://discord.gg/642wB3XC3Q) or Twitter. --- # Appendix ## Appendix A - Updating Geth If you need to update to the latest version of Geth follow these steps: ``` cd ~/lodestar-v0.30.0 sudo docker-compose down --remove-orphans sudo systemctl stop geth sudo apt update && sudo apt upgrade sudo systemctl start geth sudo systemctl status geth <-- Check for errors sudo journalctl -fu geth <-- Monitor cd ~/lodestar-v0.30.0 sudo docker-compose -f docker-compose.yml -f docker-compose.validator.yml up -d --no-recreate --remove-orphans sudo docker ps <-- Check for errors or constant restarts ``` ## Appendix B - Adding a Validator Coming Soon(tm) ## Appendix C - Expanding the Logical Volume There are cases where Ubuntu is provisioning only 200GB of a larger SSD causing users to run out of disk space when syncing their Eth1 node. The error message is similar to: `Fatal: Failed to register the Ethereum service: write /var/lib/goethereum/geth/chaindata/383234.ldb: no space left on device` To address this issue, assuming you have a SSD that is larger than 200GB, expand the space allocation for the LVM by following these steps: ``` sudo lvdisplay <-- Check your logical volume size sudo lvm lvextend -l +100%FREE /dev/ubuntu-vg/ubuntu-lv lvextend -l +100%FREE -r /dev/ubuntu-vg/ubuntu-lv exit sudo resize2fs /dev/ubuntu-vg/ubuntu-lv df -h <-- Check results ``` That should resize your disk to the maximum available space. If you need support on this please check with the [ChainSafe Lodestar Discord](https://discord.gg/642wB3XC3Q). ## Full Disclaimer This article (the guide) is for informational purposes only and does not constitute professional advice. The author does not warrant or guarantee the accuracy, integrity, quality, completeness, currency, or validity of any information in this article. All information herein is provided “as is” without warranty of any kind and is subject to change at any time without notice. The author disclaims all express, implied, and statutory warranties of any kind, including warranties as to accuracy, timeliness, completeness, or fitness of the information in this article for any particular purpose. The author is not responsible for any direct, indirect, incidental, consequential or any other damages arising out of or in connection with the use of this article or in reliance on the information available on this article. This includes any personal injury, business interruption, loss of use, lost data, lost profits, or any other pecuniary loss, whether in an action of contract, negligence, or other misuse, even if the author has been informed of the possibility.