Lodestar client Installation guide

Configurate the service

1. Configuring lodestarbeacon service user and data directory

   • Create a service user Service/User name:

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

   • Enable lodestarbeacon user access NodeJs User with NodeJs:

     sudo usermod -aG nodejsusr lodestarbeacon

   • Create a directory for Lodestar Beacon data Service data directory:

     sudo mkdir -p /var/lib/lodestar/beacon

   • Set directory ownership

     sudo chown -R lodestarbeacon:lodestarbeacon /var/lib/lodestar/beacon

2. 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: default (9000) Custom
      • 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: default (9001) Custom
      • 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: default Custom
      • 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: default (9090) Custom
      • 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: default Custom
      • Verify availability of selected port 9091

        ss -tuln | grep ':9091'

        If it returns empty response, the port 9091 is free and can be used.

3. Create configuration file for the Lodestar beacon service

   • Open the configuration file

     sudo nano /etc/systemd/system/lodestarbeacon.service

   • Copy following configuration to the file

     Installed NodeJs version on the server:
     This can be get with command $ node -v

     [Unit]
     Description=Lodestar Consensus Beacon Client (Ethereum mainnet)
     Wants=network-online.target
     After=network-online.target
     [Service]
     User=lodestarbeacon
     Group=lodestarbeacon
     Type=simple
     Restart=always
     RestartSec=5
     WorkingDirectory=/usr/local/bin/lodestar
     Environment="PATH=/home/nodejsusr/.nvm/versions/node/v20.11.0/bin:/usr/local/sbin:/usr/local/bin:/usr/sbin:/usr/bin:/sbin:/bin"
     ExecStart=/usr/local/bin/lodestar/lodestar beacon \
       --network mainnet \
       --dataDir /var/lib/lodestar/beacon \
       --execution.urls http://127.0.0.1:8551 \
       --jwt-secret /var/lib/jwtsecret/ethereum.hex \
       --checkpointSyncUrl https://beaconstate.info \
       --port 9000 \
       --discoveryPort 9000 \
       --rest.port 9596
       #--port6 9090
       #--suggestedFeeRecipient 0x.........................
     [Install]
     WantedBy=multi-user.target

     [Unit]
     Description=Lodestar Consensus Beacon Client (Gnosis Chain)
     Wants=network-online.target
     After=network-online.target
     [Service]
     User=lodestarbeacon
     Group=lodestarbeacon
     Type=simple
     Restart=always
     RestartSec=5
     WorkingDirectory=/usr/local/bin/lodestar
     Environment="PATH=/home/nodejsusr/.nvm/versions/node/v20.11.0/bin:/usr/local/sbin:/usr/local/bin:/usr/sbin:/usr/bin:/sbin:/bin"
     ExecStart=/usr/local/bin/lodestar/lodestar beacon \
       --network gnosis \
       --dataDir /var/lib/lodestar/beacon \
       --execution.urls http://127.0.0.1:8551 \
       --jwt-secret /var/lib/jwtsecret/gnosis.hex \
       --checkpointSyncUrl https://checkpoint.gnosischain.com \
       --port 9000 \
       --discoveryPort 9000 \
       --rest.port 9596
       #--port6 9090
       #--suggestedFeeRecipient 0x.........................
     [Install]
     WantedBy=multi-user.target

     Note: 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 → Lodestar

   • Press CTRL + X then Y then ENTER to save and exit the config file.
4. Reload daemon

   sudo systemctl daemon-reload

5. Run the service

   sudo systemctl start lodestarbeacon

6. Monitor the running lodestar Beacon service

   systemctl status lodestarbeacon

   journalctl -fu lodestarbeacon

7. Enable auto start on server statup

   sudo systemctl enable lodestarbeacon

   • Open Delayed Start shell

     sudo nano /usr/local/bin/delayed-start.sh

     Configurate service start inside it

     systemctl start lodestarbeacon.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

   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 service. It should be as follow:

        beaconServices="lodestarbeacon"

        If you place more services to the category, separate them with a space, see beaconServices="service1 service2 service3 ..."

   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