Blockchain Deployment and Maintenance Guide

Version: 1.0
Date: July 13, 2025
Author: M. A. Gydien assisted by AI
Project: HARVEST Blockchain Operations Manual

System Requirements
Installation Procedures
Network Configuration
Node Operation
Validator Setup
Monitoring and Maintenance
Security Hardening
Backup and Recovery
Troubleshooting
Performance Optimization

System Requirements

The HARVEST blockchain supports multiple deployment configurations to accommodate different operational requirements and resource constraints. This section outlines the hardware, software, and network requirements for various node types and deployment scenarios.

Hardware Requirements

Full Node (Recommended for Validators):

CPU: 8+ cores, 3.0+ GHz (Intel i7/AMD Ryzen 7 or equivalent)
Memory: 32 GB RAM minimum, 64 GB recommended
Storage: 1 TB NVMe SSD minimum, 2 TB recommended
Network: 1 Gbps dedicated connection with unlimited bandwidth
Redundancy: UPS power backup, RAID storage configuration

Light Node (Suitable for Wallets and Applications):

CPU: 4+ cores, 2.5+ GHz
Memory: 8 GB RAM minimum, 16 GB recommended
Storage: 100 GB SSD minimum
Network: 100 Mbps stable connection
Redundancy: Basic power backup recommended

Archive Node (For Historical Data and Analytics):

CPU: 16+ cores, 3.5+ GHz
Memory: 64 GB RAM minimum, 128 GB recommended
Storage: 5 TB NVMe SSD minimum, 10 TB recommended
Network: 10 Gbps connection for data serving
Redundancy: Enterprise-grade redundancy and backup systems

Software Requirements

Operating System Support:

Linux: Ubuntu 20.04 LTS or newer (recommended), CentOS 8+, Debian 11+
Windows: Windows Server 2019 or newer, Windows 10 Pro (development only)
macOS: macOS 11.0 or newer (development and testing only)

Required Dependencies:

Python: Version 3.9 or newer with pip package manager
Node.js: Version 16.0 or newer with npm package manager
Database: PostgreSQL 13+ or compatible database system
Networking: OpenSSL 1.1.1+ for cryptographic operations
Monitoring: Prometheus and Grafana for system monitoring

Optional Components:

Docker: For containerized deployment and management
Kubernetes: For large-scale orchestrated deployments
Load Balancer: For high-availability configurations
CDN: For serving static content and reducing latency

Network Requirements

Bandwidth Specifications:

Minimum: 10 Mbps upload/download for basic node operation
Recommended: 100 Mbps upload/download for reliable performance
Validator: 1 Gbps dedicated connection for optimal consensus participation
Archive: 10 Gbps for serving historical data to network participants

Port Configuration:

P2P Communication: Port 8080 (configurable, must be publicly accessible)
RPC Interface: Port 8090 (configurable, restrict access as needed)
Monitoring: Port 9090 for Prometheus metrics (internal access only)
Web Interface: Port 3000 for dashboard access (optional)

Firewall Requirements:

Allow inbound connections on P2P port from any IP address
Restrict RPC port access to authorized IP addresses only
Block all other inbound connections unless specifically required
Allow all outbound connections for blockchain synchronization

Installation Procedures

The HARVEST blockchain installation process varies depending on your deployment requirements and technical expertise. This section provides step-by-step instructions for different installation methods.

Automated Installation Script

The automated installation script provides the fastest and most reliable method for setting up HARVEST blockchain nodes:

# Download and run the installation script
curl -sSL https://install.harvest.network/install.sh | bash

# Follow the interactive prompts to configure your node
# The script will automatically:
# - Install required dependencies
# - Download blockchain software
# - Configure network settings
# - Initialize blockchain data
# - Start node services

Installation Options:

Node Type: Choose between full node, light node, or validator
Network: Select mainnet, testnet, or development network
Storage Location: Specify data directory location
Service Configuration: Enable automatic startup and monitoring

Manual Installation

For advanced users who require custom configurations:

# Update system packages
sudo apt update && sudo apt upgrade -y

# Install required dependencies
sudo apt install -y python3.9 python3-pip nodejs npm postgresql-13 git

# Create harvest user and directories
sudo useradd -m -s /bin/bash harvest
sudo mkdir -p /opt/harvest/{bin,data,logs,config}
sudo chown -R harvest:harvest /opt/harvest

# Download HARVEST blockchain software
cd /opt/harvest
sudo -u harvest git clone https://github.com/harvest-network/harvest-blockchain.git
cd harvest-blockchain

# Install Python dependencies
sudo -u harvest pip3 install -r requirements.txt

# Install Node.js dependencies
sudo -u harvest npm install

# Initialize configuration
sudo -u harvest python3 scripts/init-config.py

# Initialize blockchain data
sudo -u harvest python3 scripts/init-blockchain.py

# Create systemd service
sudo cp scripts/harvest-node.service /etc/systemd/system/
sudo systemctl enable harvest-node
sudo systemctl start harvest-node

Docker Deployment

Docker deployment provides isolation and simplified management:

# Pull the official HARVEST Docker image
docker pull harvest/harvest-node:latest

# Create data volume for persistent storage
docker volume create harvest-data

# Run HARVEST node container
docker run -d \
  --name harvest-node \
  --restart unless-stopped \
  -p 8080:8080 \
  -p 8090:8090 \
  -v harvest-data:/data \
  -e HARVEST_NETWORK=mainnet \
  -e HARVEST_NODE_TYPE=full \
  harvest/harvest-node:latest

# Monitor container logs
docker logs -f harvest-node

Kubernetes Deployment

For large-scale deployments with high availability:

# harvest-deployment.yaml
apiVersion: apps/v1
kind: Deployment
metadata:
  name: harvest-node
spec:
  replicas: 3
  selector:
    matchLabels:
      app: harvest-node
  template:
    metadata:
      labels:
        app: harvest-node
    spec:
      containers:
      - name: harvest-node
        image: harvest/harvest-node:latest
        ports:
        - containerPort: 8080
        - containerPort: 8090
        env:
        - name: HARVEST_NETWORK
          value: "mainnet"
        - name: HARVEST_NODE_TYPE
          value: "full"
        volumeMounts:
        - name: harvest-data
          mountPath: /data
        resources:
          requests:
            memory: "8Gi"
            cpu: "2"
          limits:
            memory: "16Gi"
            cpu: "4"
      volumes:
      - name: harvest-data
        persistentVolumeClaim:
          claimName: harvest-data-pvc

Network Configuration

Proper network configuration ensures optimal performance and security for your HARVEST blockchain node. This section covers network setup, firewall configuration, and connectivity optimization.

Network Topology

The HARVEST blockchain uses a peer-to-peer network topology where nodes connect directly to each other without central coordination. Understanding the network structure helps optimize your node's connectivity:

Seed Nodes: Well-known nodes that help new nodes discover the network. Seed nodes are operated by the HARVEST foundation and trusted community members.

Peer Discovery: Nodes automatically discover other peers through the network protocol. The discovery process includes peer exchange and reputation tracking.

Connection Management: Nodes maintain connections to multiple peers for redundancy and performance. Connection limits prevent resource exhaustion while ensuring adequate connectivity.

Firewall Configuration

Proper firewall configuration balances security with network accessibility:

# Ubuntu/Debian firewall configuration using ufw
sudo ufw default deny incoming
sudo ufw default allow outgoing

# Allow SSH access (adjust port as needed)
sudo ufw allow 22/tcp

# Allow HARVEST P2P communication
sudo ufw allow 8080/tcp

# Allow RPC access from specific IP ranges (adjust as needed)
sudo ufw allow from 192.168.1.0/24 to any port 8090

# Enable firewall
sudo ufw enable

# Verify configuration
sudo ufw status verbose

Advanced Firewall Rules:

# Rate limiting for P2P connections
sudo ufw limit 8080/tcp

# Geographic restrictions (requires GeoIP)
sudo ufw deny from country CN
sudo ufw deny from country RU

# DDoS protection
echo 'net.netfilter.nf_conntrack_max = 262144' >> /etc/sysctl.conf
echo 'net.netfilter.nf_conntrack_tcp_timeout_established = 1200' >> /etc/sysctl.conf

Load Balancing and High Availability

For production deployments requiring high availability:

HAProxy Configuration:

# /etc/haproxy/haproxy.cfg
global
    daemon
    maxconn 4096

defaults
    mode tcp
    timeout connect 5000ms
    timeout client 50000ms
    timeout server 50000ms

frontend harvest_rpc
    bind *:8090
    default_backend harvest_nodes

backend harvest_nodes
    balance roundrobin
    server node1 10.0.1.10:8090 check
    server node2 10.0.1.11:8090 check
    server node3 10.0.1.12:8090 check

Keepalived Configuration:

# /etc/keepalived/keepalived.conf
vrrp_instance VI_1 {
    state MASTER
    interface eth0
    virtual_router_id 51
    priority 100
    advert_int 1
    authentication {
        auth_type PASS
        auth_pass harvest123
    }
    virtual_ipaddress {
        10.0.1.100
    }
}

Node Operation

Operating a HARVEST blockchain node requires understanding of startup procedures, configuration management, and routine maintenance tasks. This section provides comprehensive guidance for node operators.

Node Startup and Shutdown

Starting a Node:

# Using systemd service
sudo systemctl start harvest-node

# Manual startup with custom configuration
sudo -u harvest /opt/harvest/bin/harvest-node \
  --config /opt/harvest/config/node.conf \
  --data-dir /opt/harvest/data \
  --log-level info

# Verify node startup
sudo systemctl status harvest-node
tail -f /opt/harvest/logs/node.log

Graceful Shutdown:

# Using systemd service
sudo systemctl stop harvest-node

# Manual shutdown with signal
sudo pkill -TERM harvest-node

# Force shutdown if necessary (not recommended)
sudo pkill -KILL harvest-node

Configuration Management

The HARVEST node uses a hierarchical configuration system that allows customization of all operational parameters:

Main Configuration File (/opt/harvest/config/node.conf):

[network]
# Network configuration
network_id = mainnet
listen_port = 8080
max_peers = 50
seed_nodes = seed1.harvest.network:8080,seed2.harvest.network:8080

[rpc]
# RPC interface configuration
enabled = true
listen_address = 127.0.0.1
listen_port = 8090
allowed_origins = localhost,127.0.0.1

[storage]
# Storage configuration
data_directory = /opt/harvest/data
max_cache_size = 8GB
sync_mode = full

[logging]
# Logging configuration
log_level = info
log_file = /opt/harvest/logs/node.log
max_log_size = 100MB
log_rotation = daily

[consensus]
# Consensus configuration
validator_enabled = false
validator_key_file = /opt/harvest/config/validator.key
stake_pool_id = 

[monitoring]
# Monitoring configuration
metrics_enabled = true
metrics_port = 9090
health_check_port = 8091

Environment Variables:

# Override configuration with environment variables
export HARVEST_NETWORK=mainnet
export HARVEST_DATA_DIR=/opt/harvest/data
export HARVEST_LOG_LEVEL=debug
export HARVEST_MAX_PEERS=100

Synchronization Process

New nodes must synchronize with the blockchain before they can participate in the network:

Initial Sync:

Downloads complete blockchain history from network peers
Validates all transactions and blocks cryptographically
Builds local indexes for efficient querying
Can take several hours to days depending on network speed

Fast Sync (Optional):

Downloads only recent blockchain state
Trusts cryptographic proofs for historical data
Significantly faster than full sync
Suitable for non-validator nodes

Monitoring Sync Progress:

# Check sync status via RPC
curl -s http://localhost:8090/api/sync/status | jq

# Monitor log output
tail -f /opt/harvest/logs/node.log | grep -i sync

# Check block height
curl -s http://localhost:8090/api/blockchain/height

Performance Monitoring

Continuous monitoring ensures optimal node performance:

System Metrics:

# CPU usage
top -p $(pgrep harvest-node)

# Memory usage
ps -o pid,vsz,rss,comm -p $(pgrep harvest-node)

# Disk I/O
iostat -x 1

# Network traffic
iftop -i eth0

Blockchain Metrics:

# Peer connections
curl -s http://localhost:8090/api/network/peers | jq '.count'

# Transaction pool size
curl -s http://localhost:8090/api/mempool/size

# Block processing time
curl -s http://localhost:8090/api/metrics/block_time

# Sync status
curl -s http://localhost:8090/api/sync/status

Validator Setup

Validators play a crucial role in the HARVEST blockchain by participating in consensus and block production. This section provides detailed instructions for setting up and operating a validator node.

Validator Requirements

Technical Requirements:

High-performance hardware with redundancy
Stable internet connection with low latency
24/7 uptime with minimal downtime
Security hardening and monitoring
Backup and disaster recovery procedures

Economic Requirements:

Minimum stake amount (varies by network parameters)
Sufficient HRV tokens for transaction fees
Understanding of slashing conditions and penalties
Long-term commitment to network participation

Operational Requirements:

Technical expertise in blockchain operations
Monitoring and alerting systems
Incident response procedures
Regular software updates and maintenance

Validator Key Generation

Validator keys are cryptographic credentials that enable participation in consensus:

# Generate validator keys
sudo -u harvest /opt/harvest/bin/harvest-keygen \
  --output /opt/harvest/config/validator.key \
  --type validator

# Generate VRF keys for randomness
sudo -u harvest /opt/harvest/bin/harvest-keygen \
  --output /opt/harvest/config/vrf.key \
  --type vrf

# Generate KES keys for key evolution
sudo -u harvest /opt/harvest/bin/harvest-keygen \
  --output /opt/harvest/config/kes.key \
  --type kes

# Secure key files
chmod 600 /opt/harvest/config/*.key
chown harvest:harvest /opt/harvest/config/*.key

Key Security Best Practices:

Store keys on encrypted filesystems
Use hardware security modules (HSMs) for production
Implement key rotation procedures
Maintain secure backups of all keys
Restrict access to key files

Stake Pool Registration

Validators must register their stake pools on the blockchain:

# Create stake pool certificate
sudo -u harvest /opt/harvest/bin/harvest-cli stake-pool create \
  --validator-key /opt/harvest/config/validator.key \
  --vrf-key /opt/harvest/config/vrf.key \
  --kes-key /opt/harvest/config/kes.key \
  --pledge 1000000 \
  --margin 0.05 \
  --cost 340 \
  --metadata-url https://validator.example.com/metadata.json \
  --output /opt/harvest/config/pool.cert

# Submit registration transaction
sudo -u harvest /opt/harvest/bin/harvest-cli transaction submit \
  --certificate /opt/harvest/config/pool.cert \
  --fee-payer /opt/harvest/config/payment.key

Stake Pool Metadata (metadata.json):

{
  "name": "HARVEST Validator Pool",
  "description": "Professional validator supporting agricultural blockchain",
  "ticker": "HRVST",
  "homepage": "https://validator.example.com",
  "extended": "https://validator.example.com/extended.json"
}

Validator Configuration

Configure your node for validator operation:

# Add to node.conf
[consensus]
validator_enabled = true
validator_key_file = /opt/harvest/config/validator.key
vrf_key_file = /opt/harvest/config/vrf.key
kes_key_file = /opt/harvest/config/kes.key
stake_pool_id = pool1abc123...

[performance]
# Optimize for validator performance
block_production_timeout = 5000
transaction_validation_threads = 8
memory_pool_size = 10000

Validator Monitoring

Comprehensive monitoring ensures validator reliability:

Prometheus Metrics Configuration:

# prometheus.yml
global:
  scrape_interval: 15s

scrape_configs:
  - job_name: 'harvest-validator'
    static_configs:
      - targets: ['localhost:9090']
    metrics_path: /metrics
    scrape_interval: 5s

Grafana Dashboard:

Block production rate and timing
Peer connection status and quality
System resource utilization
Validator performance metrics
Alert thresholds and notifications

Alerting Rules:

# alerts.yml
groups:
  - name: harvest-validator
    rules:
      - alert: ValidatorOffline
        expr: up{job="harvest-validator"} == 0
        for: 1m
        labels:
          severity: critical
        annotations:
          summary: "Validator node is offline"
          
      - alert: HighBlockMissRate
        expr: harvest_blocks_missed_rate > 0.05
        for: 5m
        labels:
          severity: warning
        annotations:
          summary: "High block miss rate detected"

Table of Contents​

System Requirements​

Hardware Requirements​

Software Requirements​

Network Requirements​

Installation Procedures​

Automated Installation Script​

Manual Installation​

Docker Deployment​

Kubernetes Deployment​

Network Configuration​

Network Topology​

Firewall Configuration​

Load Balancing and High Availability​

Node Operation​

Node Startup and Shutdown​

Configuration Management​

Synchronization Process​

Performance Monitoring​

Validator Setup​

Validator Requirements​

Validator Key Generation​

Stake Pool Registration​

Validator Configuration​

Validator Monitoring​

Table of Contents