Teku client Installation guide

One-page interactive guide to install Teku 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. See more.

Install client

  1. Install Java

    cd ~/downloads && wget https://download.oracle.com/java/24/latest/jdk-24_linux-x64_bin.deb
    sudo apt install ./jdk-24_linux-x64_bin.deb
    Get installed Java version: java --version
  2. Find the latest stable version of Teku on Github

    1. Find latest Teku version at Github: https://github.com/Consensys/teku/releases
    2. Write latest stable Teku version:

    This will update the url links in the guide below.

  3. Download the latest Teku version

    cd ~/downloads && curl -LO https://artifacts.consensys.net/public/teku/raw/names/teku.tar.gz/versions/25.9.1/teku-25.9.1.tar.gz
  4. Unpack the downloaded Teku version

    tar xvf teku-25.9.1.tar.gz
  5. Copy the Teku Library

    sudo cp -a ~/downloads/teku-25.9.1 /usr/local/bin/teku
  6. Remove downloaded files

    cd ~/downloads && rm teku-25.9.1.tar.gz && rm -r teku-25.9.1

Configurate the service

  • Create a user

    :
    sudo useradd --system --no-create-home --shell /bin/false tekubeacon
  • Create a folder for Tekubeacon data

    :
    sudo mkdir -p /var/lib/tekubeacon
  • Set access permission and ownership for the Teku data folder

    sudo chown -R tekubeacon:tekubeacon /var/lib/tekubeacon
  • 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

      • :
      • 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

      • :
      • 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

      • :
      • 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

      • :
      • 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

      • :
      • 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 Tekubeacon service

    1. Open Tekubeacon configuration file

      sudo nano /etc/systemd/system/tekubeacon.service
    2. Copy configuration

      [Unit]
      Description=Teku Consensus Client (Ethereum Mainnet)
      Wants=network-online.target
      After=network-online.target
      [Service]
      User=tekubeacon
      Group=tekubeacon
      Type=simple
      Restart=always
      RestartSec=5
      Environment="JAVA_OPTS=-Xmx12g"
      Environment="TEKU_OPTS=-XX:-HeapDumpOnOutOfMemoryError"
      ExecStart=/usr/local/bin/teku/bin/teku \
        --network=mainnet \
        --data-path=/var/lib/tekubeacon \
        --ee-endpoint=http://127.0.0.1:8551 \
        --ee-jwt-secret-file=/var/lib/jwtsecret/ethereum.hex \
        #--metrics-enabled=true \
        --rest-api-enabled=true \
        #--validators-proposer-default-fee-recipient=0x... \
        --checkpoint-sync-url=https://beaconstate.info
      [Install]
      WantedBy=multi-user.target

      See more arguments at https://docs.teku.consensys.io/reference/cli

      [Unit]
      Description=Teku Consensus Client (Gnosis chain)
      Wants=network-online.target
      After=network-online.target
      [Service]
      User=tekubeacon
      Group=tekubeacon
      Type=simple
      Restart=always
      RestartSec=5
      Environment="JAVA_OPTS=-Xmx12g"
      Environment="TEKU_OPTS=-XX:-HeapDumpOnOutOfMemoryError"
      ExecStart=/usr/local/bin/teku/bin/teku \
        --network=gnosis \
        --data-path=/var/lib/tekubeacon \
        --ee-endpoint=http://127.0.0.1:8551 \
        --ee-jwt-secret-file=/var/lib/jwtsecret/gnosis.hex \
        #--validators-proposer-default-fee-recipient=0x... \
        --checkpoint-sync-url=https://checkpoint.gnosischain.com \
        #--metrics-enabled=true \
        --rest-api-enabled=true
        
      [Install]
      WantedBy=multi-user.target

      See more arguments at https://docs.teku.consensys.io/reference/cli

      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 → Teku

      *Note: Update ee-jwt-secret-file, if you use different
    3. Press CTRL + X then Y then ENTER to save and exit the config file.
  • Load changes

    sudo systemctl daemon-reload

Launch Tekubeacon service

  • Start the Beacon chain service
    sudo systemctl start tekubeacon
  • Check the service
    systemctl status tekubeacon
    journalctl -fu tekubeacon
  • Start the service automatically on system startup

    sudo systemctl enable tekubeacon
    • Open Delayed Start shell
      sudo nano /usr/local/bin/delayed-start.sh

      Configurate service start inside it

      systemctl start tekubeacon.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="tekubeacon"

        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

Any issue while running Teku client?

Check Teku client emergency page.

Update Teku client Emergency for Teku client Add Teku validator Exit Teku validator