Skip to main content

Cloud Node Setup Guide

Important Prerequisites​

If you want to run a node for the SHI4GUD network and interact with official Burn Banks, you must ensure that your node address has been approved and added to the allowlist in the KTV2 contract.. To learn how to apply for node approval, please refer to the Node Application Process page.

Overview​

This guide provides step-by-step instructions for deploying SHI4GUD nodes on cloud infrastructure. While this guide uses DigitalOcean Droplets as an example, the same principles apply to other cloud providers such as AWS EC2, Google Cloud Platform, Azure, Linode, or any other VPS provider that supports Ubuntu Linux.

The guide covers:

  • Setting up a cloud server (using DigitalOcean as an example)
  • Installing required software (Go, Node.js, PM2)
  • Configuring and running multiple nodes
  • Managing nodes with PM2 process manager

Prerequisites:

  • A wallet ready on Mainnet with some ETH to cover gas fees
  • An Alchemy account with an API key (Pay As You Go tier, $5/month limit should be enough)
  • If running a node for the SHI4GUD network: Your node address must be approved and added to the KTV2 contract allowlist (see Node Application Process). This is only required when interacting with official burn banks.

Resources:

Step 1: Create Your Cloud Server Account​

This guide uses DigitalOcean as an example, but you can use any cloud provider that offers Ubuntu-based VPS instances.

DigitalOcean Setup​

  1. Go to DigitalOcean website
  2. Sign up for an account
  3. Verify your email and add a payment method

Step 2: Create a Droplet (Your Server)​

  1. Click the green "Create" button at the top
  2. Select "Droplets"
  3. Choose these settings:
    • Region: Pick one close to you
    • Image: Ubuntu 22.04 LTS
    • Plan: Basic ($6/month)
    • Authentication: Password (simpler for beginners)
    • Hostname: Pick a name like "staking-node"
  4. Click "Create Droplet"

Step 3: Termius Setup & Connection​

Install Termius​

Download Termius from: https://termius.com/download

Add New Host in Termius​

  1. Open Termius and click "New Host"
  2. Enter your droplet details:
    • Label: SHI4GUD Node
    • Address: Your droplet IP (e.g., 142.93.123.456)
    • Port: 22
    • Username: root (or your user)
  3. Add authentication:
    • Click "Keys" → "New Key"
    • Or use password authentication
  4. Click "Save"

Connect to Your Droplet​

  1. Double-click your saved host
  2. Enter password if prompted
  3. You're now connected to your droplet!

Using Termius Built-in Editor​

Termius has a built-in SFTP and file editor:

  1. Click the "SFTP" icon in the toolbar
  2. Navigate to your files
  3. Double-click any file to edit
  4. Save with Ctrl+S (Cmd+S on Mac)

Pro Tip: Create code snippets in Termius (Settings → Snippets) for frequently used commands like pm2 list, pm2 logs, etc.

Step 4: Install Required Software​

Run the following commands to install all required software:

apt update && apt upgrade -y
# Updates the package list and upgrades all installed packages

apt install golang-go -y
# Installs the Go programming language runtime and compiler

apt install curl -y
# Installs curl for downloading files from the internet

curl -fsSL https://deb.nodesource.com/setup_22.x | bash -
# Adds the NodeSource repository for Node.js 22.x

apt install nodejs -y
# Installs Node.js and npm

npm install pm2 -g
# Installs PM2 globally (process manager to keep your app running)

sudo reboot
# Reboots the system to ensure that all services and changes are fully applied

After the reboot, reconnect to your droplet.

Step 5: Set Up Basic Security​

Configure the firewall to allow SSH connections:

ufw allow OpenSSH
# Allows SSH connections through the firewall

ufw enable
# Enables the firewall (type "y" when prompted)

Step 6: Upload Your Application​

Clone from GitHub​

apt install git -y
# Installs Git version control

cd ~
# Navigate to home directory

git clone https://github.com/SHI4GUD/shi4gud-node.git
# Clone the repository

cd shi4gud-node
# Enter project directory

ls -la
# Check directory structure

Repository Location:

  • If logged in as root: /root/shi4gud-node
  • If using another user: /home/username/shi4gud-node

Expected Directory Structure:

/root/shi4gud-node/
├── src/              # Source code
├── .vscode/          # VS Code settings
├── .gitignore        # Git ignore rules
├── README.md         # Documentation
├── build.ps1         # Windows build script
├── build.sh          # Linux build script
├── go.mod            # Go module file
└── go.sum            # Go dependencies

Build the Application​

chmod +x build.sh
# Make build script executable

./build.sh
# Run build

ls -la ktoc
# Verify binary was created
# Should show: -rwxr-xr-x 1 root root ... ktoc

Build Complete! The ktoc binary is now ready at /root/shi4gud-node/ktoc

Step 7: Configuration​

Create Wrapper Script​

In Termius, use the built-in editor or create the file via command line:

cd /root/shi4gud-node
nano run.sh

Add this content:

#!/bin/bash
ENV_FILE=$1
shift # Remove first argument (env file)
set -a
source "$ENV_FILE"
set +a
exec ./ktoc "$@" # Pass all remaining arguments

Save and exit nano: Ctrl+X, then Y, then Enter

chmod +x run.sh
# Make it executable

Create Environment Files​

Create first node configuration:

nano .env.1

Add your configuration (Example with SHI):

MY_PUBLIC_KEY=--ADD YOUR WALLET PUBLIC KEY--
MY_PRIVATE_KEY=--ADD YOUR WALLET PRIVATE KEY--
DEAD_ADDR=0x000000000000000000000000000000000000dEaD
TARGET_ADDR=0x287f2611BDbed09037A8fF71C677e0a0309dEa1E
FACTORY_ADDR=0x71B9a8Cdc785Dac637056D371e762CDc0f0d9385
POOL_ADDR=0x959C7D5706AC0B5a29F506a1019Ba7F2a1C70c70
TKN_ADDR=0x243cACb4D5fF6814AD668C3e225246efA886AD5a
TKN_PRC_ADDR=0xf86bFF1a3EC62175dE2c6395214323C566354315
KT_ADDR=0xB1511DfE756342CA14a858B4896983095fEc1B51
QUERY_DELAY=200
ETH_ENDPOINT=https://eth-mainnet.g.alchemy.com/v2/ADD_YOUR_API_KEY
KT_START_BLOCK=24179279

Create additional nodes (Example with SHIB):

nano .env.2
MY_PUBLIC_KEY=--ADD YOUR WALLET PUBLIC KEY--
MY_PRIVATE_KEY=--ADD YOUR WALLET PRIVATE KEY--
DEAD_ADDR=0x000000000000000000000000000000000000dEaD
TARGET_ADDR=0x287f2611BDbed09037A8fF71C677e0a0309dEa1E
FACTORY_ADDR=0x71B9a8Cdc785Dac637056D371e762CDc0f0d9385
POOL_ADDR=0x2F62f2B4c5fcd7570a709DeC05D68EA19c82A9ec
TKN_ADDR=0x95aD61b0a150d79219dCF64E1E6Cc01f0B64C4cE
TKN_PRC_ADDR=0xf86bFF1a3EC62175dE2c6395214323C566354315
KT_ADDR=0xE9cAFc8c14C44592aB976F5450D0d40f97668ffc
QUERY_DELAY=200
ETH_ENDPOINT=https://eth-mainnet.g.alchemy.com/v2/ADD_YOUR_API_KEY
KT_START_BLOCK=24179342

Create PM2 Ecosystem Config​

nano ecosystem.config.js

Add this configuration:

module.exports = {
  apps: [
    {
      name: 'node-shi',
      script: './run.sh',
      args: '.env.1 -run -chunkSize 500 -waitDuration 5m',
      cwd: '/root/shi4gud-node',
      autorestart: true,
      max_restarts: 10,
      restart_delay: 5000
    },
    {
      name: 'node-shib',
      script: './run.sh',
      args: '.env.2 -run -chunkSize 500 -waitDuration 5m',
      cwd: '/root/shi4gud-node',
      autorestart: true,
      max_restarts: 10,
      restart_delay: 5000
    }
  ]
};

Final Directory Structure:

/root/shi4gud-node/
├── src/
├── ktoc                  # Built binary
├── run.sh                # Wrapper script
├── .env.1                # Node 1 config
├── .env.2                # Node 2 config
├── ecosystem.config.js   # PM2 config
├── build.sh
├── go.mod
└── README.md

Step 8: Start Nodes​

Start All Nodes​

cd /root/shi4gud-node
# Make sure you're in the project directory

pm2 start ecosystem.config.js
# Start all nodes

Save Configuration​

pm2 save
# Save the current PM2 process list

Enable Auto-Start on Boot​

pm2 startup
# Generate startup script

✅ Nodes Started Successfully! Your SHI4GUD nodes are now running and will auto-start on reboot!

Verify Nodes are Running​

pm2 list

Expected output:

┌────┬────────────────────┬─────────┬─────────┬─────────┬──────────┐
│ id │ name               │ mode    │ ↺       │ status  │ cpu      │
├────┼────────────────────┼─────────┼─────────┼─────────┼──────────┤
│ 0  │ node-shi           │ fork    │ 0       │ online  │ 0%       │
│ 1  │ node-shib          │ fork    │ 0       │ online  │ 0%       │
└────┴────────────────────┴─────────┴─────────┴─────────┴──────────┘

Step 9: Managing Nodes​

View All Processes​

pm2 list          # List all processes
pm2 status        # Alternative command

View Logs​

pm2 logs                    # All logs (live)
pm2 logs node-shi           # Specific node logs
pm2 logs --lines 100        # Last 100 lines
pm2 logs --err              # Error logs only
pm2 flush                   # Clear all logs

Monitor Resources​

pm2 monit                   # Real-time monitoring dashboard
pm2 show node-shi           # Detailed info for specific node

Restart Nodes​

pm2 restart node-shi        # Restart specific node
pm2 restart all             # Restart all nodes
pm2 reload all              # Zero-downtime restart

Stop/Delete Nodes​

pm2 stop node-shi           # Stop specific node
pm2 stop all                # Stop all nodes
pm2 delete node-shi         # Remove from PM2
pm2 delete all              # Remove all

Step 10: Updating the Node​

When a new version of the node software is released, use the update script below to pull the latest code, rebuild the binary, and restart your PM2 processes. You only need to set up the script once; after that, run it whenever you want to update.

One-Time Setup: Create the Update Script​

  1. Go to your project directory:
cd /root/shi4gud-node
# Or: cd ~/shi4gud-node if not using root
  1. Create the update script:
nano update.sh
  1. Paste the following script into the editor:

Tip: In most terminals (e.g. Termius), use Ctrl+Shift+V to paste from your clipboard.

#!/bin/bash
# Production update script for SHI4GUD node
# Pull latest code, rebuild, restart PM2 instances

set -e  # stop on any error

# Explicit project directory
PROJECT_DIR="/root/shi4gud-node"
cd "$PROJECT_DIR"

echo "🔄 Pulling latest code from GitHub..."
git pull origin master

echo "🛠 Building updated binary..."
chmod +x build.sh
./build.sh

echo "♻️ Restarting PM2 processes..."
pm2 restart all

echo "💾 Saving PM2 process list..."
pm2 save

echo "✅ Update complete!"

  1. Save and exit nano: Ctrl+X, then Y, then Enter.

  2. Make the script executable (stay in /root/shi4gud-node):

chmod +x update.sh
# Makes the update script executable

Running an Update​

Whenever you want to update to the latest node version:

cd /root/shi4gud-node
# Ensure you're in the project directory

./update.sh
# Run the update script

The script will pull the latest code, rebuild the binary, restart all PM2 processes, and save the process list. Allow a few minutes for the build and restart to complete.

What Success Looks Like​

When the update completes successfully, you should see output similar to:

  • Build: [SUCCESS] Build process completed successfully and a message that the executable was built at /root/shi4gud-node/ktoc
  • PM2 restart: Confirmations (✓) for each node (e.g. shi-node, shib-node or node-shi, node-shib depending on your config)
  • Status table: Both nodes listed with status: online and a short uptime (e.g. 0s right after restart)
  • Save: Successfully saved in /root/.pm2/dump.pm2
  • Done: ✅ Update complete!

If your output matches this, the update succeeded.

After Updating: Check Logs​

Always verify that the nodes are running without errors:

pm2 logs
# View live logs from all nodes (Ctrl+C to exit)

pm2 logs --lines 50
# Or view the last 50 lines

If you see no errors and the nodes are processing as expected, the update is complete. For future updates, run ./update.sh from /root/shi4gud-node whenever you want to pull and deploy the latest code.

Additional Notes​

  • Security: Always keep your private keys secure. Never commit .env files to version control.
  • Monitoring: Regularly check your node logs to ensure they're running correctly.
  • Updates: Use the update script described in Step 10: Updating the Node. After one-time setup, run ./update.sh from the project directory whenever you want to update.
  • Multiple Nodes: You can run multiple nodes on the same server by creating additional .env files and adding entries to ecosystem.config.js.