Linux Setup Guides

Follow these simple steps in order. Take your time and make sure each step completes successfully before moving to the next one.

01 / Install Geth (Execution Client)

Before doing anything else, your Linux server needs geth installed. Geth is the core software that executes smart contracts.

sudo add-apt-repository -y ppa:ethereum/ethereum

sudo apt-get update

sudo apt-get install ethereum -y

geth version

02 / Network & Firewall Configuration

CRITICAL STEP: Before you run the blockchain, you MUST open specific network ports. If these ports are closed, your node will blindly wander the internet with zero peers, and it will fail to synchronize. You need to open these ports on your Operating System Firewall (e.g., Ubuntu UFW) AND your Cloud Provider's Firewall Dashboard (AWS, Vultr, GCP).

sudo ufw allow 30303
sudo ufw allow 13000/tcp
sudo ufw allow 12000/udp
sudo ufw allow 3500/tcp
sudo ufw enable

03 / Clone Repository & Initialize Node

Fully Automated Magic: You don't need to manually configure complicated consensus clients. Our join_network.sh script will automatically detect if you are running an Intel/AMD or Apple/ARM chip, download the correct binaries, generate secure JWT tokens, and configure the background systemd services for you.

🔗 View ZugChain Validator Suite on GitHub ↗

Download the ZugChain suite and run the automated installer:

git clone https://github.com/ZugChainLabs/zugchain-validator-configs.git

cd zugchain-validator-configs/validator

chmod +x join_network.sh

sudo ./join_network.sh

04 / Key Generation & Secure Import

To participate in consensus, generate your keys offline using the official ZugChain CLI, deposit 32,000 ZUG, and upload your keystore-m_...json file to your server (e.g., into a folder named ~/zug_keys). Then, import it using the command below:

/usr/local/bin/validator accounts import \
    --keys-dir=$HOME/zug_keys \
    --wallet-dir=/opt/zugchain/data/validators \
    --account-password-file=$HOME/zug_keys/password.txt

CRITICAL - Auto-Restart Requirement: During the import step above, you will be asked to create a NEW Wallet Password. You MUST immediately save this password into a specific file. If you do not do this, your validator will completely fail to turn back on if your server ever restarts, resulting in severe slashing penalties! Run this command:

echo "YOUR_NEW_WALLET_PASSWORD" > /opt/zugchain/data/validators/wallet-password.txt

05 / Start the Node & Monitor

With your keys imported and password saved, you can officially ignite the validator service.

sudo systemctl start zugchain-validator

# Install colorized log viewer
sudo apt-get install ccze -y

# View Live Real-Time Logs
journalctl -fu zugchain-validator | ccze -A