> For the complete documentation index, see [llms.txt](https://zugchain.gitbook.io/zugchain/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://zugchain.gitbook.io/zugchain/validator-operations/linux-setup-guides.md).

# 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.

#### <mark style="color:$primary;">01 / Install Geth (Execution Client)</mark>

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

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

```bash
sudo apt-get update
```

```bash
sudo apt-get install ethereum -y
```

```bash
geth version
```

#### <mark style="color:$primary;">02 / Network & Firewall Configuration</mark>

{% hint style="danger" %}
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).
{% endhint %}

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

#### <mark style="color:$primary;">03 / Clone Repository & Initialize Node</mark>

{% hint style="success" %}
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.
{% endhint %}

{% hint style="info" %}
🔗 [View ZugChain Validator Suite on GitHub ↗](https://github.com/ZugChainLabs/zugchain-validator-configs)&#x20;
{% endhint %}

*Download the ZugChain suite and run the automated installer:*

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

```bash
cd zugchain-validator-configs/validator
```

```bash
chmod +x join_network.sh
```

```bash
sudo ./join_network.sh
```

#### <mark style="color:$primary;">04 / Key Generation & Secure Import</mark>

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:

```bash
/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
```

{% hint style="warning" %}
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:
{% endhint %}

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

#### <mark style="color:$primary;">05 / Start the Node & Monitor</mark>

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

```bash
sudo systemctl start zugchain-validator
```

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

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


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://zugchain.gitbook.io/zugchain/validator-operations/linux-setup-guides.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.