Install Lighthouse client

One-page interactive guide to install Lighthouse client and configurate it for running on supported chain.

Disclaimer

This guide is for informational purposes only. The author nor website owner does not guarantee accuracy of the information in this guide and is not responsible for any damages or losses incurred by following the guide.

Lighthouse client can be used for staking on various supported chains. Client installation is always only one, used by services with an individual configuration (different service name, data path and ports in use).

Interactive variables

System:
User:
SSH port:
CPU type:

Execution layer

Client:
Service:
- Data:
- Port:
- P2P:
- RPC:

Consensus layer

Client:
NodeJs version:
jdk ver version:
Beacon service:
- Data:
- Port:
- P2P:
- Quic:

Install Lighthouse client

Find the latest stable version of Lighthouse on Github
- Find latest Lighthouse version at https://github.com/sigp/lighthouse/releases
- Write latest stable lighthouse version:
  
  This will update the url links in the guide below.

Download Lighthouse version `6.0.1` to your node

cd ~/downloads && curl -LO https://github.com/sigp/lighthouse/releases/download/v6.0.1/lighthouse-v6.0.1-x86_64-unknown-linux-gnu.tar.gz

Extract downloaded file

$ tar xvf lighthouse-v6.0.1-x86_64-unknown-linux-gnu.tar.gz

Replace old Lighthouse client for new

$ sudo cp ~/downloads/lighthouse /usr/local/bin

Remove downloaded files

$ cd ~/downloads && rm lighthouse-v6.0.1-x86_64-unknown-linux-gnu.tar.gz && rm -r lighthouse

Configurate the service

Create a user for lighthouse beacon Service/User name:

$ sudo useradd --system --no-create-home --shell /bin/false lighthousebeacon

Create a directory for data Service data directory:
```
$ sudo mkdir -p /var/lib/lighthouse/beacon
```

Set permission for accessing the directory

$ sudo chown -R lighthousebeacon:lighthousebeacon /var/lib/lighthouse/beacon

Communication ports selection

Each service on the server needs a custom port for communication. Through ports, consensus client communicates with other peers in the network as well as other services running on the server, such as validator clients. There is an IPv4 and IPv6 variant, depending on the ISP support / preference. Each protocol version needs custom port. If you are not sure what to select, continue with default IPv4 port.
1. Configurate public IPv4 port for P2P communication with other peers
  - Choose P2P communication port:
  - Verify availability of selected port 9000
    ss -tuln | grep ':9000'
    
    If it returns empty response, the port 9000 is free and can be used.
  - Enable traffic on the port through UFW
    $ sudo ufw allow 9000
  - Disable IPv6 traffic on the port
    
    List allowed ports
    sudo ufw status numbered
    
    Find order number for V6, see 9000 (V6) and remove it with the following line
    sudo ufw delete <Number>
2. QUIC IPv4 port
  - Choose QUIC IPv4 port:
  - Verify availability of selected port 9001
    ss -tuln | grep ':9001'
    
    If it returns empty response, the port 9001 is free and can be used.
3. Beacon API port for internal communication
  - Choose Beacon API port:
  - Verify availability of selected port 5052
    ss -tuln | grep ':5052'
    
    If it returns empty response, the port 5052 is free and can be used.
1. Configurate public IPv6 port for P2P communication with other peers
  - P2P communication port:
  - Verify availability of selected port 9090
    ss -tuln | grep ':9090'
    
    If it returns empty response, the port 9090 is free and can be used.
  - Enable traffic on the port through UFW
    $ sudo ufw allow 9090
  - Disable IPv6 traffic on the port
    
    List allowed ports
    sudo ufw status numbered
    
    Find order number for V6, see 9090 and remove it with the following line
    sudo ufw delete <Number>
2. QUIC IPv6 port
  - Choose QUIC IPv4 port:
  - Verify availability of selected port 9091
    ss -tuln | grep ':9091'
    
    If it returns empty response, the port 9091 is free and can be used.
Create configuration file for Lighthouse Beacon service

Open Lighthouse Beacon configuration file
```
$ sudo nano /etc/systemd/system/lighthousebeacon.service
```
Copy the configuration below into the file. If needed, check flags documentation.
```
[Unit]
Description=Lighthouse Consensus Client BN (Ethereum Mainnet)
Wants=network-online.target
After=network-online.target

[Service]
User=lighthousebeacon
Group=lighthousebeacon
Type=simple
Restart=always
RestartSec=5
ExecStart=/usr/local/bin/lighthouse bn \
  --network mainnet \
  --datadir /var/lib/lighthouse \
  --http \
  --execution-endpoint http://127.0.0.1:8551 \
  --execution-jwt /var/lib/jwtsecret/ethereum.hex \
#  --target-peers 80 \
  --checkpoint-sync-url https://beaconstate.info \
  --port 9000 \
  --port6 9090 \
#  --discovery-port 9000 \
  --quic-port 9001 \
  --quic-port6 9091 \
  --http-port 5052

[Install]
WantedBy=multi-user.target
```
Notes:
- You can find all available flags at https://lighthouse-book.sigmaprime.io/help_bn.html
- Update execution-jwt, if you use different
- You can uncomment --target-peers to reduce bandwidth
- You can configurate checkpoint-sync-url for a quick synchronization from a selected Checkpoint sync endpoint. After enabling it, verify, that you are on on the expected chain, see https://beaconstate.info/ → Get started → Lighthouse
- If you operate more nodes in the local network, you can configurate --trusted-peers flag. You can get peer_id from BeaconChain API through PROTOCOL://IP:PORT/eth/v1/node/identity` command.
```
[Unit]
Description=Lighthouse Consensus Client BN (Gnosis Network)
Wants=network-online.target
After=network-online.target

[Service]
User=lighthousebeacon
Group=lighthousebeacon
Type=simple
Restart=always
RestartSec=5
ExecStart=/usr/local/bin/lighthouse bn \
  --network gnosis \
  --datadir /var/lib/lighthouse \
#  --subscribe-all-subnets \
  --execution-endpoint http://localhost:8551 \
  --execution-jwt /var/lib/jwtsecret/gnosis.hex \
#  --target-peers 80 \
#  --checkpoint-sync-url https://checkpoint.gnosischain.com \
  --http \
  --port 9000 \
  --port6 9090 \
#  --discovery-port 9000 \
  --quic-port 9001 \
  --quic-port6 9091 \
  --http-port 5052

[Install]
WantedBy=multi-user.target
```
Notes:
- You can find all available flags at https://lighthouse-book.sigmaprime.io/help_bn.html
- Update execution-jwt, if you use different
- You can uncomment checkpoint-sync-url for a quick synchronization from a checpoint. After enabling it, verify, that you are on on the expected chain, see https://checkpoint.gnosischain.com/ → Get started → Lighthouse
- You can uncomment --target-peers to reduce bandwidth
- If you operate more nodes in the local network, you can configurate --trusted-peers flag. You can get peer_id from BeaconChain API through PROTOCOL://IP:PORT/eth/v1/node/identity` command.
*Note: Update execution-jwt, if you use different
Press CTRL + X then Y then ENTER to save and exit the config file.
Load changes made in config files to the system
```
$ sudo systemctl daemon-reload
```
Start the service
```
$ sudo systemctl start lighthousebeacon
```

Check the state

$ systemctl status lighthousebeacon
$ journalctl -fu lighthousebeacon

Activate service to start automatically
$ sudo systemctl enable lighthousebeacon
NOTE: This option requires installed Start with Delay util.

Open Delayed Start shell
sudo nano /usr/local/bin/delayed-start.sh

Configurate service start inside it

systemctl start lighthousebeacon.service

Be sure, delayed-start.service service controlling delayed-start.sh is enabled for auto start with system startup
sudo systemctl enable delayed-start.service
NOTE: This option requires following installed utils:
- Start with Delay util with delayed-start.service.
- Staking Manager util.
A guide to install each util is attached on the Github.
1. Configurate Staking Manager util
  - Open the configuration file
    sudo nano /usr/local/etc/staking/config/clients.conf
    
    If the file is empty, generate it with command sudo /usr/local/bin/staking.sh init
  - Set link to proper services. It should be as follow:
    beaconServices="lighthousebeacon.service"
2. Activate service to start automatically on OS startup
  - Open Start with delay util
    sudo nano /usr/local/bin/delayed-start.sh
  - Place or uncomment a command to start the Beacon client(s)
    /usr/local/bin/staking.sh start beacon
  - Verify, that a service `delayed-start.service` exists and is automatically launched on system start.
    sudo systemctl enable delayed-start.service

Launch validator instance / validator(s)

Instance ID:
Fee Recipient wallet:
Validator Instance service config
- Name:
- User:
- Data:

Do you want to create a new validation instance or extend exisiting instance for more validators?

Create a directory for validator instance data
```
sudo mkdir -p /var/lib/lighthouse/vi1
```

Load keystores to `/var/lib/lighthouse/vi1`

Directory with Deposit Data keystores:

sudo /usr/local/bin/lighthouse --network mainnet account validator import --reuse-password --directory $HOME/keystores/ddk_i1 --datadir /var/lib/lighthouse/vi1

sudo /usr/local/bin/lighthouse --network gnosis account validator import --reuse-password --directory $HOME/keystores/ddk_i1 --datadir /var/lib/lighthouse/vi1

Insert keystores encryption password (the one used during keystores generation) on request
If there are keystores with different encryption password, repeat the process for each encryption password

Create a service user for the validator instance

sudo useradd --system --no-create-home --shell /bin/false lighthouse-vi1

Set ownership of `/var/lib/lighthouse/vi1` to `validators-i1` user

sudo chown -R lighthouse-vi1:lighthouse-vi1 /var/lib/lighthouse/vi1

Create configuration service file for `lighthouse-vi1` service

Open the configuration file

sudo nano /etc/systemd/system/lighthouse-vi1.service

Copy the configuration below into the file.

What's fee recipient wallet?
What's your execution client?

[Unit]
Description=Lighthouse Validator Instance (Mainnet)
Wants=network-online.target
After=network-online.target
[Service]
User=lighthouse-vi1
Group=lighthouse-vi1
Type=simple
Restart=always
RestartSec=5
ExecStart=/usr/local/bin/lighthouse vc \
  --network mainnet \
  --datadir /var/lib/lighthouse/vi1 \
  --suggested-fee-recipient 0xXXXXXXXXXXXXXXXX \
  --beacon-nodes http://localhost:5052 \
  --graffiti "Nethermind+Lighthouse"
[Install]
WantedBy=multi-user.target

[Unit]
Description=Lighthouse Validator Instance (Gnosis Network)
Wants=network-online.target
After=network-online.target
[Service]
User=lighthouse-vi1
Group=lighthouse-vi1
Type=simple
Restart=always
RestartSec=5
ExecStart=/usr/local/bin/lighthouse vc \
  --network gnosis \
  --datadir /var/lib/lighthouse/vi1 \
  --suggested-fee-recipient 0xXXXXXXXXXXXXXXXX \
  --beacon-nodes http://localhost:5052 \
  --graffiti "Nethermind+Lighthouse"
[Install]
WantedBy=multi-user.target

Press CTRL + X then Y then ENTER to save and exit the config file.

Other configurations
Nothing to do. You are ok.
- Extend Staking manager clients.conf
  Insert lighthouse-vi1 into clients.conf file that is used by Staking Manager.
```
sudo nano /usr/local/etc/staking/config/clients.conf
```

Stop running validator instance lighthouse-vi1
```
sudo systemctl stop lighthouse-vi1
```
Extend /var/lib/lighthouse/vi1 for new keystores
```
sudo /usr/local/bin/lighthouse --network mainnet account validator import --reuse-password --directory $HOME/keystores/ddk_i1 --datadir /var/lib/lighthouse/vi1
```
```
sudo /usr/local/bin/lighthouse --network gnosis account validator import --reuse-password --directory $HOME/keystores/ddk_i1 --datadir /var/lib/lighthouse/vi1
```
- You will be requested to insert keystores encryption password (the one used during keystores generation)
- If there are keystores with different encryption password, repeat the process for each encryption password
- Already existing keystores in the directory will be skipped

Load processed changes to the system
```
sudo systemctl daemon-reload
```
Start the validator instance
```
sudo systemctl start lighthouse-vi1
```

Check the running validator instance

systemctl status lighthouse-vi1

journalctl -fu lighthouse-vi1

Activate service to start automatically on OS startup
```
$ sudo systemctl enable lighthouse-vi1
```
NOTE: This option requires installed Start with Delay util.
- Open Delayed Start shell
```
sudo nano /usr/local/bin/delayed-start.sh
```
  Configurate service start inside it
```
systemctl start lighthouse-vi1
```
- Be sure, delayed-start.service service controlling delayed-start.sh is enabled for auto start with system startup
```
sudo systemctl enable delayed-start.service
```

Exit validator instance / validator(s)

Instance ID:
Fee Recipient wallet:
Validator Instance service config
- Name:
- User:
- Data:

A validator can be exited with following command:

lighthouse --network "$chain" account validator exit --keystore /path/to/keystore --password-file "$HOME/exit/keystore-password.txt" --beacon-node http://localhost:5052

Where:

--network is mainnet for Ethereum chain and gnosis for Gnosis chain
--keystore is a path to the keystore file of specific validator
--password-file is a file with exit passowrd placed in
--beacon-node is a beaconnode url

Example request can look as below:

/usr/local/bin/lighthouse --network mainnet account validator exit --keystore /var/lib/lighthouse/vi1/validators/keystore... --beacon-node http://localhost:5052

/usr/local/bin/lighthouse --network gnosis account validator exit --keystore /var/lib/lighthouse/vi1/validators/keystore... --beacon-node http://localhost:5052

For confirmation, place exit phrase Exit my validator

Follow instructions from Exit Lighthouse validators on Github.

Install a script for bulk exit
Create ~/exit/keystore-password.txt file with keystores password. It's the passowrd selected during validator keys generation. The passowrd can be also found at validator_definitions.yml file, see
```
sudo nano /var/lib/lighthouse-validatorInstance/validator_definitions.yml
```

Perform the exit all validators in selected instance request

/usr/local/bin/lighthouse_exit_validators.sh mainnet /var/lib/ethereum/lighthouse/vi1/validators http://localhost:5052

/usr/local/bin/lighthouse_exit_validators.sh gnosis /var/lib/gnosis/lighthouse/vi1/validators http://localhost:5052

Replace chain for ethereum / gnosis
Replace /var/lib/gnosis/lighthouse/vi1/validators/ for a path to your instance keystores

Remove the password from ~/exit/keystore-password.txt

See more at official documentation, if needed.