🌐 Republic AI Node Setup Guide

Republic is a decentralized system that leverages blockchain technology to coordinate and verify computational tasks.

---

📋 Table of Contents

• About Republic
• System Requirements
• Recommended VPS Providers
• Prerequisites
• Installation
• Running the Node
• Register & Connect Your Node
• Monitoring
• Useful Commands
• Troubleshooting

---

About Republic

Republic is a decentralized AI compute network that uses blockchain technology to coordinate and verify computational tasks. Node operators contribute compute resources and earn points through the Republic Portal.

Note: GPU is optional but provides better points on the portal.

---

System Requirements

Minimum (CPU Node)

Component	Requirement
CPU	4 vCPU
RAM	8 GB
Storage	100 GB SSD
OS	Ubuntu 20.04 / 22.04 LTS
Network	100 Mbps

Recommended (GPU Node)

Component	Requirement
CPU	8 vCPU
RAM	16 GB
Storage	200 GB NVMe SSD
GPU	NVIDIA RTX 3080 / A100 or equivalent
OS	Ubuntu 20.04 / 22.04 LTS
Network	1 Gbps

---

Recommended VPS Providers

Provider	Link
Contabo	https://Lihat.info/contabo
Vultr	https://Lihat.info/vultr
Servarica	https://Lihat.info/servarica
VPSAG	https://Lihat.info/vpsag
Hetzner	https://Lihat.info/hetzner

---

Prerequisites

1. Update System

sudo apt update && sudo apt upgrade -y

2. Install Required Packages

sudo apt install -y curl wget git screen unzip build-essential

3. Install Docker

curl -fsSL https://get.docker.com -o get-docker.sh
sudo sh get-docker.sh
sudo usermod -aG docker $USER
newgrp docker

Verify Docker is installed:

docker --version

4. Install Docker Compose

sudo curl -L "https://github.com/docker/compose/releases/latest/download/docker-compose-$(uname -s)-$(uname -m)" -o /usr/local/bin/docker-compose
sudo chmod +x /usr/local/bin/docker-compose
docker-compose --version

5. (Optional) Install NVIDIA Drivers for GPU Support

sudo apt install -y nvidia-driver-535
sudo apt install -y nvidia-container-toolkit
sudo systemctl restart docker

Verify GPU is detected:

nvidia-smi

---

Installation

1. Register on Republic Portal

Go to https://points.republicai.io/?ref=ED1206 and create an account. After registration, you will receive an API Key from your dashboard.

2. Clone the Repository

git clone https://github.com/republicai/node.git
cd node

3. Configure Environment Variables

cp .env.example .env
nano .env

Fill in the required fields:

REPUBLIC_API_KEY=your_api_key_here
REPUBLIC_NODE_NAME=your_node_name
NODE_TYPE=cpu   # Change to "gpu" if you have a GPU

Save and exit (CTRL+X, then Y, then ENTER).

---

Running the Node

Start the Node (CPU)

docker-compose up -d

Start the Node (GPU)

docker-compose -f docker-compose.gpu.yml up -d

Check Node is Running

docker-compose ps
docker-compose logs -f

---

Register & Connect Your Node

After starting the node, go to your Republic Dashboard and:

1. Navigate to My Nodes
2. Click Add Node
3. Enter your node's public IP address
4. Paste your Node ID (found in the logs):

docker-compose logs | grep "Node ID"

5. Click Verify & Connect

Your node should now appear as Active on the dashboard.

---

Monitoring

View Live Logs

docker-compose logs -f --tail=100

Check Container Status

docker ps -a

Check Resource Usage

docker stats

Run Inside Container

docker exec -it republic-node bash

---

Useful Commands

Action	Command
Start node	docker-compose up -d
Stop node	docker-compose down
Restart node	docker-compose restart
View logs	docker-compose logs -f
Update node	git pull && docker-compose pull && docker-compose up -d

Run in Screen Session (Recommended for VPS)

screen -S republic
docker-compose up
# Detach: CTRL+A then D
# Reattach:
screen -r republic

---

Updating the Node

cd node
git pull origin main
docker-compose pull
docker-compose down
docker-compose up -d

---

Troubleshooting

Node not connecting to portal

• Make sure your API Key in .env is correct
• Check that ports are open on your VPS firewall:

sudo ufw allow 3000/tcp
sudo ufw allow 8080/tcp
sudo ufw enable

Docker permission denied

sudo usermod -aG docker $USER
newgrp docker

Out of memory / OOM errors

Increase swap space:

sudo fallocate -l 4G /swapfile
sudo chmod 600 /swapfile
sudo mkswap /swapfile
sudo swapon /swapfile
echo '/swapfile none swap sw 0 0' | sudo tee -a /etc/fstab

GPU not detected in container

sudo nvidia-ctk runtime configure --runtime=docker
sudo systemctl restart docker

---

Community & Support

• Portal: https://points.republicai.io/?ref=ED1206
• Twitter/X: @RepublicAI
• Discord: Republic Discord
• Telegram: Republic Telegram

---

License

This guide is open-source and intended for educational purposes. Always refer to the official Republic Documentation for the most up-to-date information.

---

Made with ❤️ for the Republic community