diff --git a/pages/devs/validators/run-full-node.mdx b/pages/devs/validators/run-full-node.mdx index 4441a3f..26cb25e 100644 --- a/pages/devs/validators/run-full-node.mdx +++ b/pages/devs/validators/run-full-node.mdx @@ -4,21 +4,260 @@ import { Callout } from 'nextra/components' > How to become a Validator on Allora -This guide provides instructions on how to run a full node for the Allora network. There are two primary methods for running an Allora node: using `docker compose` (preferred) or using a [script](https://github.com/allora-network/allora-chain/blob/main/scripts/l1_node.sh). It's important to choose the method that best suits your environment and needs. +This guide provides instructions on how to run a full node for the Allora network. There are two primary methods for running an Allora node: using systemd with cosmosvisor for easier upgrade management (recommended) or using docker compose. It's important to choose the method that best suits your environment and needs. *** ## Prerequisites - Git -- Docker with `docker compose` +- Go (version 1.21 or later) - Basic command-line knowledge +- Linux/Unix environment with systemd +- curl and jq utilities *** -## Method 1: Using `docker compose` (Recommended) +## Method 1: Using systemd with cosmosvisor (Recommended) -Running the Allora node with `docker compose` simplifies the setup and ensures consistency across different environments. +Running the Allora node with systemd and cosmosvisor provides production-grade reliability and easier binary upgrade management. This is the recommended approach for validators and production environments. + +### Step 1: Install cosmosvisor + +First, install cosmosvisor, which will manage binary upgrades: + +```shell +go install cosmossdk.io/tools/cosmovisor/cmd/cosmovisor@latest +``` + +Verify the installation: + +```shell +cosmovisor version +``` + +### Step 2: Install allorad Binary + +Download the latest `allorad` binary from the releases page: + +1. Navigate to the [Allora Chain Releases page](https://github.com/allora-network/allora-chain/releases/latest). +2. Download the `allorad` binary appropriate for your operating system (e.g., `allorad-linux-amd64`, `allorad-darwin-amd64`). +3. Rename and move the binary to a standard location: + +```shell +# Rename the downloaded binary +mv ./allorad-linux-amd64 ./allorad # Adjust filename as needed + +# Move to system path +sudo mv ./allorad /usr/local/bin/allorad + +# Make executable +sudo chmod +x /usr/local/bin/allorad +``` + +### Step 3: Initialize the Node + +Initialize your node (replace `` with your desired node name): + +```shell +allorad init --chain-id allora-testnet-1 +``` + +### Step 4: Download Network Configuration + +Download the testnet configuration files: + +```shell +# Download genesis.json +curl -s https://raw.githubusercontent.com/allora-network/networks/main/allora-testnet-1/genesis.json > $HOME/.allorad/config/genesis.json + +# Download config.toml +curl -s https://raw.githubusercontent.com/allora-network/networks/main/allora-testnet-1/config.toml > $HOME/.allorad/config/config.toml + +# Download app.toml +curl -s https://raw.githubusercontent.com/allora-network/networks/main/allora-testnet-1/app.toml > $HOME/.allorad/config/app.toml +``` + +### Step 5: Configure Seeds and Peers + +Configure seeds and persistent peers for network connectivity: + +```shell +# Fetch and set seeds +SEEDS=$(curl -s https://raw.githubusercontent.com/allora-network/networks/main/allora-testnet-1/seeds.txt) +sed -i.bak -e "s/^seeds *=.*/seeds = \"$SEEDS\"/" $HOME/.allorad/config/config.toml + +# Optionally set persistent peers +PEERS=$(curl -s https://raw.githubusercontent.com/allora-network/networks/main/allora-testnet-1/peers.txt) +sed -i.bak -e "s/^persistent_peers *=.*/persistent_peers = \"$PEERS\"/" $HOME/.allorad/config/config.toml +``` + +### Step 6: Configure cosmosvisor + +Set up the cosmosvisor directory structure and environment: + +```shell +# Set environment variables +export DAEMON_NAME=allorad +export DAEMON_HOME=$HOME/.allorad +export DAEMON_RESTART_AFTER_UPGRADE=true + +# Create cosmosvisor directories +mkdir -p $DAEMON_HOME/cosmovisor/genesis/bin +mkdir -p $DAEMON_HOME/cosmovisor/upgrades + +# Copy the current binary to genesis +cp /usr/local/bin/allorad $DAEMON_HOME/cosmovisor/genesis/bin/ +``` + +### Step 7: Configure State Sync (Optional but Recommended) + +State sync allows your node to quickly catch up with the network. Create and run this state sync script: + +```shell +cat > state_sync.sh << 'EOF' +#!/bin/bash + +set -e + +# Choose your preferred RPC endpoint +SNAP_RPC="https://allora-rpc.testnet.allora.network" +CONFIG_TOML_PATH="$HOME/.allorad/config/config.toml" + +echo "Using RPC Endpoint: $SNAP_RPC" +echo "Fetching latest block height..." + +LATEST_HEIGHT=$(curl -s $SNAP_RPC/block | jq -r .result.block.header.height) +if [ -z "$LATEST_HEIGHT" ] || [ "$LATEST_HEIGHT" == "null" ]; then + echo "Error: Could not fetch latest height" + exit 1 +fi + +BLOCK_HEIGHT_OFFSET=2000 +BLOCK_HEIGHT=$((LATEST_HEIGHT - BLOCK_HEIGHT_OFFSET)) + +echo "Fetching trust hash for block $BLOCK_HEIGHT..." +TRUST_HASH=$(curl -s "$SNAP_RPC/block?height=$BLOCK_HEIGHT" | jq -r .result.block_id.hash) +if [ -z "$TRUST_HASH" ] || [ "$TRUST_HASH" == "null" ]; then + echo "Error: Could not fetch trust hash" + exit 1 +fi + +echo "Updating config for state sync..." +RPC_SERVERS="$SNAP_RPC,$SNAP_RPC" + +sed -i.bak -E \ + -e "s|^(enable[[:space:]]*=[[:space:]]*).*$|\\1true|" \ + -e "s|^(rpc_servers[[:space:]]*=[[:space:]]*).*$|\\1\"$RPC_SERVERS\"|" \ + -e "s|^(trust_height[[:space:]]*=[[:space:]]*).*$|\\1$BLOCK_HEIGHT|" \ + -e "s|^(trust_hash[[:space:]]*=[[:space:]]*).*$|\\1\"$TRUST_HASH\"|" \ + "$CONFIG_TOML_PATH" + +echo "State sync configuration updated successfully" +EOF + +chmod +x state_sync.sh +./state_sync.sh +``` + +### Step 8: Reset Node Data + +Reset existing data while keeping the address book: + +```shell +allorad tendermint unsafe-reset-all --home $HOME/.allorad --keep-addr-book +``` + + +**Warning**: This command deletes blockchain data. Only run this on a fresh node or when you intend to resync from scratch. + + +### Step 9: Create systemd Service + +Create a systemd service file for cosmosvisor: + +```shell +sudo tee /etc/systemd/system/allorad.service > /dev/null < +**Security Note**: `DAEMON_ALLOW_DOWNLOAD_BINARIES` is set to `false` for security. Validators should manually place upgrade binaries in the appropriate directories. + + +### Step 10: Start the Service + +Enable and start the systemd service: + +```shell +sudo systemctl daemon-reload +sudo systemctl enable allorad +sudo systemctl start allorad +``` + +### Monitoring and Management + +Monitor your node logs: + +```shell +sudo journalctl -u allorad -f +``` + +Check service status: + +```shell +sudo systemctl status allorad +``` + +Check sync status: + +```shell +curl -s http://localhost:26657/status | jq .result.sync_info.catching_up +``` + +Once this returns `false`, your node is fully synced. + +### Managing Upgrades with cosmosvisor + +When a governance upgrade is approved, prepare for it by placing the new binary: + +```shell +# For an upgrade named "v1.0.0", create the upgrade directory +mkdir -p $DAEMON_HOME/cosmovisor/upgrades/v1.0.0/bin + +# Download and place the new binary (replace with actual URL) +# wget NEW_BINARY_URL -O $DAEMON_HOME/cosmovisor/upgrades/v1.0.0/bin/allorad +# chmod +x $DAEMON_HOME/cosmovisor/upgrades/v1.0.0/bin/allorad +``` + + +**Info**: cosmosvisor will automatically switch to the new binary at the upgrade height specified in the governance proposal. Monitor governance proposals and prepare upgrade binaries in advance. + + +*** + +## Method 2: Using `docker compose` + +Running the Allora node with `docker compose` simplifies the setup and ensures consistency across different environments, but requires manual upgrade management. ### Step 1: Clone the Allora Chain Repository