Nexus Protocol Testnet Node Setup Guide

This guide will help you set up a Nexus Protocol compute node on the testnet using Docker Compose. Follow these steps carefully to ensure a successful deployment and start earning rewards by contributing computational resources to the network.

Prerequisites

System Requirements

• Operating System: Ubuntu 22.04/24.04 LTS x64 (or any Docker-compatible OS)
• CPU: 2+ cores recommended
• Memory: 12GB RAM minimum (16GB recommended)
• Storage: 50GB+ available disk space
• Network: Stable internet connection
• Software: Docker and Docker Compose installed
• Access: Root or sudo privileges

Network Information

Component	Value	Description
Network	Nexus Beta	Current beta testing network
Environment	Beta Testing	Active testing phase
Node Type	Compute Node	Provides computational resources
Deployment	Docker Compose	Containerized deployment
Registry	Nexus Web App	Node registration interface

tip

This guide uses Docker Compose for easy deployment and management. The setup automatically handles the Nexus CLI installation and node configuration.

Update System Packages

sudo -i

# Update package list and install required tools
apt update
apt install -y make git-core libssl-dev pkg-config build-essential protobuf-compiler libudev-dev curl jq wget aria2

Step 1: Obtain Your Node ID

Before setting up the node, you need to register and obtain a Node ID from the Nexus platform.

Method 1: Web Registration (Recommended)

# Open your web browser and visit the Nexus application
# URL: https://app.nexus.xyz/nodes

# 1. Register an account or log in to your existing account
# 2. Navigate to the nodes section
# 3. Click the "Add CLI Node" button
# 4. The system will generate a unique Node ID
# 5. Copy and save this Node ID for the next steps

Method 2: CLI Registration

# Download and install the Nexus CLI
curl https://cli.nexus.xyz/ | sh

# Register your wallet address (replace with your actual wallet address)
nexus-network register-user --wallet-address YOUR_WALLET_ADDRESS

# Register a new node and get Node ID
nexus-network register-node

Expected Output:

No node ID provided. Registering a new node in environment: Environment::Beta, URL: https://beta.orchestrator.nexus.xyz
Node registered successfully with ID: 13146643

info

Important: Save your Node ID securely. You'll need it for node configuration and to track your rewards.

Step 2: Prepare Project Files

Create a new directory for your Nexus node and set up the required files.

Create Project Directory

# Create project directory
mkdir -pv /data/nexus-node && cd /data/nexus-node

# Set your Node ID as environment variable (replace with your actual Node ID)
export NODE_ID="YOUR_NODE_ID_HERE"
export VERSION="YOUR_NODE_CURRENT_VERSION"

Create Entrypoint Script

cat > entrypoint.sh << 'EOF'
#!/usr/bin/env bash

set -euo pipefail

# Get Node ID from command line argument or environment variable
NODE_ID=${1:-${NODE_ID:-}}

if [ -z "$NODE_ID" ]; then
    echo "Error: NODE_ID is required"
    echo "Usage: $0 <node-id>"
    echo "Or set NODE_ID environment variable"
    exit 1
fi

echo "Starting nexus-network with node-id: ${NODE_ID}"
echo "Connecting to Nexus Beta environment..."

# Start the Nexus network node
exec /usr/local/bin/nexus-network start --node-id "${NODE_ID}" --headless --no-background-color
EOF

chmod +x entrypoint.sh

Create Dockerfile

cat > Dockerfile << 'EOF'
FROM ubuntu:24.04

ARG VERSION=v0.10.5

ENV DEBIAN_FRONTEND=noninteractive

RUN apt-get update \
    && apt-get install -y --no-install-recommends \
         libssl3 \
         ca-certificates \
         wget \
    && rm -rf /var/lib/apt/lists/*

RUN wget -O /usr/local/bin/nexus-network https://github.com/nexus-xyz/nexus-cli/releases/download/${VERSION}/nexus-network-linux-x86_64 \
    && chmod +x /usr/local/bin/nexus-network

COPY entrypoint.sh /usr/local/bin/entrypoint.sh
RUN chmod +x /usr/local/bin/entrypoint.sh

ENTRYPOINT ["/usr/local/bin/entrypoint.sh"]
EOF

Create Docker Compose Configuration

cat > docker-compose.yaml << EOF
services:
  nexus-node:
    container_name: nexus-node
    restart: always
    build:
      context: .
      args:
        VERSION: ${VERSION}
    stdin_open: true
    tty: true
    environment:
      - NODE_ID=\${NODE_ID}
    command: ["\${NODE_ID}"]
    deploy:
      resources:
        reservations:
          cpus: '1'
          memory: 8g
    logging:
      driver: "json-file"
      options:
        max-size: "100m"
        max-file: "3"
EOF

Create Environment File

cat > .env << EOF
# Replace with your actual Node ID obtained from Step 1
NODE_ID=$NODE_ID
EOF

warning

Important: Replace YOUR_NODE_ID_HERE in the .env file with your actual Node ID obtained from Step 1.

Step 3: Deploy the Node

Build and Start the Node

# Build the Docker image
docker compose build

# Start the node in the background
docker compose up -d

Verify Node Status

# View node logs
docker compose logs -f nexus-node

# Check container status
docker compose ps

# View recent logs (last 100 lines)
docker compose logs --tail=100 nexus-node

Expected Log Output:

Starting nexus-network with node-id: 21194545
Connecting to Nexus Beta environment...
Refresh [2025-07-25 03:28:16] Task Fetcher: [Task step 1 of 3] Fetching tasks...Note: CLI tasks are harder to solve, so they receive 10 times more points than web provers
Refresh [2025-07-25 03:28:16] Task Fetcher: Queue status: +2 tasks → 2 total (2% full)
Success [2025-07-25 03:28:22] Prover 0: [Task step 2 of 3] Proof completed successfully (Task ID: GT-01K0ZSJPC0Q1FGFN2SYN34F2HA)

Step 4: Monitor Your Node

Check Node Performance

# Check resource usage
docker stats nexus-node

# View container details
docker inspect nexus-node

Node Dashboard

Access your node dashboard through the Nexus web application:

1. Visit https://app.nexus.xyz/nodes
2. Log in to your account
3. Find your node using the Node ID
4. Monitor performance, earnings, and statistics

Step 5: Node Management

Basic Operations

# Stop the node
docker compose down

# Restart the node
docker compose restart

# View logs
docker compose logs -f

# Update and rebuild (when new versions are available)
docker compose down
docker compose build --no-cache
docker compose up -d

Resource Configuration

You can adjust resource limits by editing the docker-compose.yaml file:

deploy:
  resources:
    limits:
      cpus: '4'        # Increase CPU limit
      memory: 16g      # Increase memory limit
    reservations:
      cpus: '2'        # Minimum CPU reservation
      memory: 12g      # Minimum memory reservation

Environment Variables

Additional configuration options in .env file:

# Node configuration
NODE_ID=your_node_id_here

Step 6: Updates and Maintenance

Updating Node Software

# Stop the current node
docker compose down

# Rebuild with latest Nexus CLI
docker compose build --no-cache

# Start the updated node
docker compose up -d

# Verify the update
docker compose logs -f

Troubleshooting

Common Issues

Node fails to start:

# Check logs for error messages
docker compose logs nexus-node

# Verify Node ID is set correctly
cat .env

# Rebuild the image
docker compose build --no-cache
docker compose up -d

Monitor container resource usage

docker stats nexus-node

# Adjust resource limits in docker-compose.yaml if needed

Log Management

# Rotate logs manually
docker compose down
docker system prune -f
docker compose up -d

# View specific log levels
docker compose logs | grep -i "error\|warn"

# Export logs for analysis
docker compose logs --since 24h > nexus-logs-$(date +%Y%m%d).txt

Earning Rewards

How Rewards Work

• Computational Contribution: Earn rewards by providing computational resources to the network
• Task Completion: Rewards are distributed based on successfully completed computational tasks
• Network Participation: Consistent uptime and availability increase earning potential
• Resource Quality: Higher performance hardware may earn higher rewards

Monitoring Earnings

1. Web Dashboard: Check your earnings through the Nexus web application
2. Node Statistics: Monitor your node's contribution and performance metrics
3. Reward History: View detailed reward history and payment schedules

Support Resources

For help and support:

• Nexus Documentation: docs.nexus.xyz
• Node Setup Guide: docs.nexus.xyz/layer-1/vision/overview
• Discord Community: discord.gg/nexus
• GitHub: github.com/nexus-xyz
• Twitter: @nexus_xyz

---

info

This setup creates a production-ready Nexus compute node that will contribute to the verifiable computation network and earn rewards based on your computational contributions.

warning

Important Notes:

• Keep your Node ID secure and backed up
• Monitor your node regularly for optimal performance
• Ensure stable internet connection for consistent earnings
• Update your node software regularly for the latest features and security patches