d-bis/proxmox

Fork 0

Files

defiQUG b45c2006be Refactor code for improved readability and performance

2025-12-21 22:32:09 -08:00

7.1 KiB

Raw Blame History

Validated Set Deployment Guide

Complete guide for deploying a validated Besu node set using the script-based approach.

Overview

This guide covers deploying a validated set of Besu nodes (validators, sentries, RPC) on Proxmox VE LXC containers using automated scripts. The deployment uses a script-based approach with static-nodes.json for peer discovery (no boot node required).

Prerequisites

Proxmox VE 7.0+ installed
Root access to Proxmox host
Sufficient resources (RAM, disk, CPU)
Network connectivity
Source project with Besu configuration files

Deployment Methods

Method 1: Complete Deployment (Recommended)

Deploy everything from scratch in one command:

cd /opt/smom-dbis-138-proxmox
sudo ./scripts/deployment/deploy-validated-set.sh \
    --source-project /path/to/smom-dbis-138

What this does:

Deploys all containers (validators, sentries, RPC)
Copies configuration files from source project
Bootstraps the network (generates and deploys static-nodes.json)
Validates the deployment

Method 2: Step-by-Step Deployment

If you prefer more control, deploy step by step:

# Step 1: Deploy containers
sudo ./scripts/deployment/deploy-besu-nodes.sh

# Step 2: Copy configuration files
SOURCE_PROJECT=/path/to/smom-dbis-138 \
    ./scripts/copy-besu-config.sh

# Step 3: Bootstrap network
sudo ./scripts/network/bootstrap-network.sh

# Step 4: Validate validators
sudo ./scripts/validation/validate-validator-set.sh

Method 3: Bootstrap Existing Containers

If containers are already deployed and configured:

# Quick bootstrap (just network bootstrap)
sudo ./scripts/deployment/bootstrap-quick.sh

# Or use the full script with skip options
sudo ./scripts/deployment/deploy-validated-set.sh \
    --skip-deployment \
    --skip-config \
    --source-project /path/to/smom-dbis-138

Detailed Steps

Step 1: Prepare Source Project

Ensure your source project has the required files:

smom-dbis-138/
├── config/
│   ├── genesis.json
│   ├── permissions-nodes.toml
│   ├── permissions-accounts.toml
│   ├── static-nodes.json (will be generated/updated)
│   ├── config-validator.toml
│   ├── config-sentry.toml
│   └── config-rpc-public.toml
└── keys/
    └── validators/
        ├── validator-1/
        ├── validator-2/
        ├── validator-3/
        ├── validator-4/
        └── validator-5/

Step 2: Review Configuration

Check your deployment configuration:

cat config/proxmox.conf
cat config/network.conf

Key settings:

VALIDATOR_START, VALIDATOR_COUNT - Validator VMID range
SENTRY_START, SENTRY_COUNT - Sentry VMID range
RPC_START, RPC_COUNT - RPC VMID range
CONTAINER_OS_TEMPLATE - OS template to use

Step 3: Run Deployment

Execute the deployment script:

sudo ./scripts/deployment/deploy-validated-set.sh \
    --source-project /path/to/smom-dbis-138

Step 4: Monitor Progress

The script will output progress for each phase:

=========================================
Phase 1: Deploy Containers
=========================================
[INFO] Deploying Besu nodes...
[✓] Besu nodes deployed

=========================================
Phase 2: Copy Configuration Files
=========================================
[INFO] Copying Besu configuration files...
[✓] Configuration files copied

=========================================
Phase 3: Bootstrap Network
=========================================
[INFO] Bootstrapping network...
[INFO] Collecting enodes from validators...
[✓] Network bootstrapped

=========================================
Phase 4: Validate Deployment
=========================================
[INFO] Validating validator set...
[✓] All validators validated successfully!

Step 5: Verify Deployment

After deployment completes, verify everything is working:

# Check all containers are running
pct list | grep -E "1000|1001|1002|1003|1004|1500|1501|1502|1503|2500|2501|2502"

# Check service status
for vmid in 1000 1001 1002 1003 1004; do
    echo "=== Validator $vmid ==="
    pct exec $vmid -- systemctl status besu-validator --no-pager -l
done

# Check consensus is active (blocks being produced)
pct exec 2500 -- curl -s -X POST \
    -H "Content-Type: application/json" \
    -d '{"jsonrpc":"2.0","method":"eth_blockNumber","params":[],"id":1}' \
    http://localhost:8545 | python3 -m json.tool

Health Checks

Check Individual Node Health

# Human-readable output
sudo ./scripts/health/check-node-health.sh 1000

# JSON output (for automation)
sudo ./scripts/health/check-node-health.sh 1000 --json

Validate Validator Set

sudo ./scripts/validation/validate-validator-set.sh

This checks:

Container and service status
Validator keys exist and are accessible
Configuration files are present
Consensus participation

Troubleshooting

Containers Won't Start

# Check container status
pct status <vmid>

# View container console
pct console <vmid>

# Check logs
pct exec <vmid> -- journalctl -xe

Services Won't Start

# Check service status
pct exec <vmid> -- systemctl status besu-validator

# View service logs
pct exec <vmid> -- journalctl -u besu-validator -f

# Check configuration
pct exec <vmid> -- cat /etc/besu/config-validator.toml

Network Connectivity Issues

# Check P2P port is listening
pct exec <vmid> -- netstat -tuln | grep 30303

# Check peer connections (if RPC enabled)
pct exec <vmid> -- curl -s -X POST \
    -H "Content-Type: application/json" \
    -d '{"jsonrpc":"2.0","method":"admin_peers","params":[],"id":1}' \
    http://localhost:8545

# Verify static-nodes.json
pct exec <vmid> -- cat /etc/besu/static-nodes.json

Consensus Issues

# Check validator is participating
pct exec <vmid> -- journalctl -u besu-validator --no-pager | grep -i "consensus\|qbft\|proposing"

# Verify validator keys
pct exec <vmid> -- ls -la /keys/validators/

# Check genesis file
pct exec <vmid> -- cat /etc/besu/genesis.json | python3 -m json.tool

Rollback

If deployment fails, you can remove containers:

# Remove specific containers
for vmid in 1000 1001 1002 1003 1004 1500 1501 1502 1503 2500 2501 2502; do
    pct stop $vmid 2>/dev/null || true
    pct destroy $vmid 2>/dev/null || true
done

Then re-run the deployment after fixing any issues.

Post-Deployment

After successful deployment:

Monitor Logs: Keep an eye on service logs for the first few hours
Verify Consensus: Ensure blocks are being produced
Check Resources: Monitor CPU, memory, and disk usage
Network Health: Verify all nodes are connected
Backup: Consider creating snapshots of working containers

Next Steps

Set up monitoring (Prometheus, Grafana)
Configure backups
Document node endpoints
Set up alerting
Plan for maintenance windows

7.1 KiB Raw Blame History