RepublicAI · erhnysr · Mar 2, 2026 · Mar 3, 2026
diff --git a/docs/wsl2-windows-setup-guide.md b/docs/wsl2-windows-setup-guide.md
@@ -0,0 +1,236 @@
+# Republic AI Validator Node Setup on Windows (WSL2 + GPU)
+
+This guide covers setting up a Republic AI validator node on **Windows 11** using **WSL2 (Ubuntu 24.04)** with full **GPU compute support** via NVIDIA CUDA and Docker.
+
+> **Why WSL2?** Many validators run on Windows laptops or desktops. This guide enables GPU-accelerated inference without requiring a dedicated Linux machine.
+
+---
+
+## Prerequisites
+
+| Requirement | Minimum |
+|---|---|
+| OS | Windows 10 (Build 19041+) or Windows 11 |
+| RAM | 16GB+ |
+| Storage | 100GB+ free on WSL2 drive |
+| GPU | NVIDIA GPU with CUDA support (6GB+ VRAM recommended) |
+| NVIDIA Driver | 525.x or later (Windows driver) |
+
+---
+
+## Step 1: Enable WSL2 and Install Ubuntu 24.04
+
+Open **PowerShell as Administrator** and run:
+```powershell
+wsl --install -d Ubuntu-24.04
+```
+
+After installation, restart your computer and set WSL2 as default:
+```powershell
+wsl --set-default-version 2
+```
+
+Verify WSL2 is active:
+```powershell
+wsl -l -v
+```
+
+You should see `VERSION 2` next to Ubuntu-24.04.
+
+---
+
+## Step 2: Configure WSL2 Memory and Resources
+
+Create or edit `C:\Users\<YourUsername>\.wslconfig`:
+```ini
+[wsl2]
+memory=8GB
+processors=4
+swap=4GB
+```
+
+Restart WSL2:
+```powershell
+wsl --shutdown
+wsl
+```
+
+---
+
+## Step 3: Install NVIDIA CUDA Toolkit in WSL2
+
+> **Important:** Do NOT install NVIDIA drivers inside WSL2. Only install the CUDA toolkit. WSL2 uses your Windows NVIDIA driver automatically.
+
+Inside WSL2 Ubuntu terminal:
+```bash
+wget https://developer.download.nvidia.com/compute/cuda/repos/wsl-ubuntu/x86_64/cuda-keyring_1.1-1_all.deb
+sudo dpkg -i cuda-keyring_1.1-1_all.deb
+sudo apt update
+sudo apt install -y cuda-toolkit-11-8
+```
+
+Add CUDA to PATH:
+```bash
+echo 'export PATH=/usr/local/cuda-11.8/bin:$PATH' >> ~/.bashrc
+echo 'export LD_LIBRARY_PATH=/usr/local/cuda-11.8/lib64:$LD_LIBRARY_PATH' >> ~/.bashrc
+source ~/.bashrc
+```
+
+Verify:
+```bash
+nvidia-smi
+nvcc --version
+```
+
+---
+
+## Step 4: Install Docker with NVIDIA GPU Support
+```bash
+curl -fsSL https://get.docker.com | sh
+sudo usermod -aG docker $USER
+newgrp docker
+
+curl -fsSL https://nvidia.github.io/libnvidia-container/gpgkey | sudo gpg --dearmor -o /usr/share/keyrings/nvidia-container-toolkit-keyring.gpg
+curl -s -L https://nvidia.github.io/libnvidia-container/stable/deb/nvidia-container-toolkit.list | \
+  sed 's#deb https://#deb [signed-by=/usr/share/keyrings/nvidia-container-toolkit-keyring.gpg] https://#g' | \
+  sudo tee /etc/apt/sources.list.d/nvidia-container-toolkit.list
+
+sudo apt update
+sudo apt install -y nvidia-container-toolkit
+sudo nvidia-ctk runtime configure --runtime=docker
+sudo systemctl restart docker
+```
+
+Test:
+```bash
+docker run --rm --gpus all nvidia/cuda:11.8.0-base-ubuntu22.04 nvidia-smi
+```
+
+---
+
+## Step 5: Prevent Laptop Sleep When Lid is Closed
+
+1. Open **Control Panel** → **Power Options**
+2. Click **"Choose what closing the lid does"**
+3. Set **"When I close the lid"** to **"Do nothing"** for both Battery and Plugged in
+4. Click **Save changes**
+
+---
+
+## Step 6: Fix DNS Resolution (If Needed)
+```bash
+sudo tee /etc/resolv.conf << 'EOF'
+nameserver 8.8.8.8
+nameserver 8.8.4.4
+EOF
+```
+
+---
+
+## Step 7: Install Republic AI Node
+
+Follow the standard installation from [testnet guide](../testnet/readme.md), then continue below for GPU-specific configuration.
+```bash
+sudo tee /etc/systemd/system/republicd.service << 'EOF'
+[Unit]
+Description=Republic AI Node
+After=network-online.target
+
+[Service]
+User=$USER
+ExecStart=$(which republicd) start --home $HOME/.republicd
+Restart=on-failure
+RestartSec=3
+LimitNOFILE=65535
+
+[Install]
+WantedBy=multi-user.target
+EOF
+
+sudo systemctl daemon-reload
+sudo systemctl enable republicd
+sudo systemctl start republicd
+```
+
+---
+
+## Step 8: Set Up Auto Compute with Unjail Protection
+```bash
+cat > ~/auto_compute.sh << 'SCRIPT'
+#!/bin/bash
+VALIDATOR_ADDRESS="raivaloper1YOUR_ADDRESS_HERE"
+WALLET_NAME="validator"
+CHAIN_ID="raitestnet_77701-1"
+NODE="tcp://localhost:43657"
+
+while true; do
+    JAILED=$(republicd query staking validator $VALIDATOR_ADDRESS \
+        --node $NODE --output json 2>/dev/null | \
+        python3 -c "import sys,json; d=json.load(sys.stdin); print(d['validator']['jailed'])" 2>/dev/null)
+
+    if [ "$JAILED" = "True" ]; then
+        echo "$(date): Validator jailed! Sending unjail..."
+        republicd tx slashing unjail \
+            --from $WALLET_NAME \
+            --chain-id $CHAIN_ID \
+            --gas auto --gas-adjustment 1.5 \
+            --gas-prices 1000000000arai \
+            --node $NODE --keyring-backend test -y
+        sleep 30
+    fi
+    sleep 300
+done
+SCRIPT
+chmod +x ~/auto_compute.sh
+nohup ~/auto_compute.sh > ~/auto_compute.log 2>&1 &
+```
+
+---
+
+## Step 9: Set Up Public Endpoint with Cloudflare Tunnel
+
+WSL2 does not have a public IP. Use Cloudflare Tunnel to expose your result upload endpoint:
+```bash
+curl -L https://github.com/cloudflare/cloudflared/releases/latest/download/cloudflared-linux-amd64 \
+  -o cloudflared
+chmod +x cloudflared
+sudo mv cloudflared /usr/local/bin/
+
+cd /var/lib/republic/jobs
+nohup python3 -m http.server 8080 > /tmp/http_server.log 2>&1 &
+nohup cloudflared tunnel --url http://localhost:8080 > /tmp/cloudflare.log 2>&1 &
+sleep 10
+cat /tmp/cloudflare.log | grep trycloudflare
+```
+
+---
+
+## Troubleshooting
+
+### GLIBC Version Error
+```bash
+ldd --version
+sudo apt update && sudo apt upgrade -y
+```
+
+### Docker GPU Not Detected
+```bash
+docker info | grep -i runtime
+sudo nvidia-ctk runtime configure --runtime=docker
+sudo systemctl restart docker
+```
+
+### Validator Jailed After Downtime
+```bash
+republicd tx slashing unjail \
+  --from validator \
+  --chain-id raitestnet_77701-1 \
+  --gas auto --gas-adjustment 1.5 \
+  --gas-prices 1000000000arai \
+  --node tcp://localhost:43657 \
+  --keyring-backend test -y
+```
+
+---
+
+*This guide was contributed by a community validator running Republic AI on WSL2 with NVIDIA RTX 4050.*
diff --git a/testnet/TROUBLESHOOTING.md b/testnet/TROUBLESHOOTING.md
@@ -0,0 +1,44 @@
+# Republic AI Node - Troubleshooting Guide
+
+Common issues during Republic AI testnet node setup on WSL.
+
+## 1. Wrong RPC port
+Default port is 26657 but Republic uses 43657.
+Check your port: grep "laddr" ~/.republicd/config/config.toml
+Use: republicd status --node tcp://localhost:43657
+
+## 2. Block height stuck at 0
+State sync trust_height is outdated. Use snapshot instead:
+curl -L https://snapshot.vinjan-inc.com/republic/latest.tar.lz4 | lz4 -dc - | tar -xf - -C $HOME/.republicd
+
+## 3. Wrong app version error
+Download v0.3.0 binary:
+curl -L https://github.com/RepublicAI/networks/releases/download/v0.3.0/republicd-linux-amd64 -o republicd
+cp republicd ~/.republicd/cosmovisor/genesis/bin/republicd
+
+## 4. Wrong home directory
+Use ~/.republicd not ~/.republic in all commands.
+
+## 5. Database locked error
+pkill -9 -f republicd && pkill -9 -f cosmovisor
+Or: sudo systemctl stop republicd
+
+## 6. Cosmovisor DAEMON_NAME not set
+DAEMON_NAME=republicd DAEMON_HOME=$HOME/.republicd cosmovisor run start --home ~/.republicd --chain-id raitestnet_77701-1
+
+## 7. Systemd service setup (WSL)
+sudo tee /etc/systemd/system/republicd.service << EOF
+[Unit]
+Description=Republic Node
+After=network-online.target
+[Service]
+User=$USER
+Environment="DAEMON_NAME=republicd"
+Environment="DAEMON_HOME=$HOME/.republicd"
+ExecStart=/home/$USER/go/bin/cosmovisor run start --home /home/$USER/.republicd --chain-id raitestnet_77701-1
+Restart=always
+RestartSec=3
+[Install]
+WantedBy=multi-user.target
+EOF
+sudo systemctl daemon-reload && sudo systemctl enable republicd && sudo systemctl start republicd