From 42f3ba4e60300296770faf3ad1a93e92d6d5ad70 Mon Sep 17 00:00:00 2001 From: aitbc Date: Wed, 20 May 2026 09:34:52 +0200 Subject: [PATCH] feat: add integrated blockchain node deployment automation - Add deployment script for integrated blockchain node with mempool support - Create comprehensive setup documentation from scratch - Add agent workflow for automated deployment - Support both bare metal and container deployments - Include verification steps and troubleshooting guide - Provide configuration templates for hub and follower nodes --- .../deploy-integrated-blockchain-node.md | 236 ++++++++++++++ docs/deployment/INTEGRATED_NODE_SETUP.md | 295 +++++++++++++++++ .../deploy-integrated-blockchain-node.sh | 297 ++++++++++++++++++ 3 files changed, 828 insertions(+) create mode 100644 .windsurf/workflows/deploy-integrated-blockchain-node.md create mode 100644 docs/deployment/INTEGRATED_NODE_SETUP.md create mode 100755 scripts/deployment/deploy-integrated-blockchain-node.sh diff --git a/.windsurf/workflows/deploy-integrated-blockchain-node.md b/.windsurf/workflows/deploy-integrated-blockchain-node.md new file mode 100644 index 00000000..3572d0d2 --- /dev/null +++ b/.windsurf/workflows/deploy-integrated-blockchain-node.md @@ -0,0 +1,236 @@ +--- +description: Deploy integrated blockchain node with mempool support +--- + +# Integrated Blockchain Node Deployment Workflow + +This workflow deploys the integrated blockchain node (with full mempool support) to a target host or container. This is the recommended approach for production deployments. + +## Prerequisites + +- Target host with SSH access +- Python 3.13+ installed on target +- Root or sudo access on target +- Git installed on target + +## Workflow Steps + +### 1. Verify Target Environment + +```bash +# Check Python version +ssh $TARGET "python3 --version" + +# Check if git is available +ssh $TARGET "git --version" + +# Check if systemd is available +ssh $TARGET "systemctl --version" +``` + +### 2. Clone Repository + +```bash +# Clone AITBC repository to target +ssh $TARGET "sudo git clone https://gitea.bubuit.net:3000/oib/aitbc.git /opt/aitbc" +``` + +### 3. Run Deployment Script + +```bash +# Execute deployment script on target +ssh $TARGET "sudo bash /opt/aitbc/scripts/deployment/deploy-integrated-blockchain-node.sh" +``` + +### 4. Verify Deployment + +```bash +# Check service status +ssh $TARGET "sudo systemctl status aitbc-blockchain-node --no-pager" + +# Check RPC endpoint +ssh $TARGET "curl -s http://localhost:8006/rpc/head" + +# Check mempool endpoint +ssh $TARGET "curl -s http://localhost:8006/rpc/mempool" +``` + +### 5. Configure for Production + +```bash +# Edit blockchain configuration +ssh $TARGET "sudo nano /etc/aitbc/blockchain.env" + +# Set production values +# ENABLE_BLOCK_PRODUCTION=true/false +# CHAIN_ID=ait-mainnet +# NODE_ROLE=hub/follower + +# Restart service to apply changes +ssh $TARGET "sudo systemctl restart aitbc-blockchain-node" +``` + +## Container Deployment + +### For incus Containers + +```bash +# Create container +TARGET_CONTAINER="aitbc-container" +incus launch ubuntu:22.04 $TARGET_CONTAINER + +# Push repository to container +incus file push -r /opt/aitbc $TARGET_CONTAINER/opt/ + +# Run setup inside container +incus exec $TARGET_CONTAINER -- bash /opt/aitbc/scripts/deployment/deploy-integrated-blockchain-node.sh + +# Verify deployment +incus exec $TARGET_CONTAINER -- systemctl status aitbc-blockchain-node --no-pager +incus exec $TARGET_CONTAINER -- curl -s http://localhost:8006/rpc/mempool +``` + +### For ns3 Container (hub.aitbc.bubuit.net) + +```bash +# SSH to ns3 +ssh ns3 + +# Stop standalone node +incus exec aitbc -- systemctl stop aitbc-blockchain-node-3 +incus exec aitbc -- systemctl disable aitbc-blockchain-node-3 + +# Clone repository +incus exec aitbc -- git clone https://gitea.bubuit.net:3000/oib/aitbc.git /opt/aitbc + +# Run deployment script +incus exec aitbc -- bash /opt/aitbc/scripts/deployment/deploy-integrated-blockchain-node.sh + +# Verify deployment +incus exec aitbc -- curl -s http://localhost:8006/rpc/mempool +``` + +## Configuration Templates + +### Hub Node Configuration + +```env +# /etc/aitbc/blockchain.env +CHAIN_ID=ait-mainnet +RPC_BIND_HOST=0.0.0.0 +RPC_BIND_PORT=8006 +P2P_BIND_HOST=0.0.0.0 +P2P_BIND_PORT=8001 +ENABLE_BLOCK_PRODUCTION=true +GOSSIP_BROADCAST_URL=redis://127.0.0.1:6379 +CROSS_SITE_REMOTE_ENDPOINTS= +``` + +```env +# /etc/aitbc/node.env +NODE_ID=hub.aitbc.bubuit.net +ISLAND_ID=ait-public-island +CHAIN_ID=ait-mainnet +NODE_ROLE=hub +P2P_BIND_PORT=8001 +``` + +### Follower Node Configuration + +```env +# /etc/aitbc/blockchain.env +CHAIN_ID=ait-mainnet +RPC_BIND_HOST=0.0.0.0 +RPC_BIND_PORT=8006 +P2P_BIND_HOST=0.0.0.0 +P2P_BIND_PORT=8001 +ENABLE_BLOCK_PRODUCTION=false +GOSSIP_BROADCAST_URL=redis://127.0.0.1:6379 +CROSS_SITE_REMOTE_ENDPOINTS=https://hub.aitbc.bubuit.net/rpc +``` + +```env +# /etc/aitbc/node.env +NODE_ID=follower-$(hostname) +ISLAND_ID=ait-public-island +CHAIN_ID=ait-mainnet +NODE_ROLE=follower +P2P_BIND_PORT=8001 +``` + +## Verification Steps + +After deployment, verify: + +1. **Service Status:** + ```bash + systemctl is-active aitbc-blockchain-node + ``` + +2. **RPC Endpoint:** + ```bash + curl -s http://localhost:8006/rpc/head | jq + ``` + +3. **Mempool Endpoint:** + ```bash + curl -s http://localhost:8006/rpc/mempool | jq + ``` + +4. **P2P Connectivity:** + ```bash + netstat -tlnp | grep 8001 + ``` + +5. **No Errors in Logs:** + ```bash + journalctl -u aitbc-blockchain-node -n 100 --no-pager | grep -i error + ``` + +## Troubleshooting + +### Service Won't Start + +```bash +# Check logs +journalctl -u aitbc-blockchain-node -n 50 --no-pager + +# Check configuration +python3 -m aitbc_chain.main --check-config + +# Verify environment files +cat /etc/aitbc/blockchain.env +cat /etc/aitbc/node.env +``` + +### Mempool Endpoint Returns 404 + +This should not happen with integrated node. If it does: + +```bash +# Verify using correct port (8006, not 8082) +curl -s http://localhost:8006/rpc/mempool + +# Check if integrated node is running +ps aux | grep aitbc_chain.main +``` + +### Port Conflicts + +```bash +# Find process using port +lsof -i :8006 + +# Kill conflicting process +kill -9 +``` + +## Migration from Standalone + +See [Blockchain Node Implementation Guide](../../docs/blockchain/IMPLEMENTATION_GUIDE.md) for detailed migration instructions. + +## Related Documentation + +- [Integrated Node Setup Guide](../../docs/deployment/INTEGRATED_NODE_SETUP.md) +- [Blockchain Node Implementation Guide](../../docs/blockchain/IMPLEMENTATION_GUIDE.md) +- [Deployment Documentation](../../docs/deployment/) diff --git a/docs/deployment/INTEGRATED_NODE_SETUP.md b/docs/deployment/INTEGRATED_NODE_SETUP.md new file mode 100644 index 00000000..5bc46664 --- /dev/null +++ b/docs/deployment/INTEGRATED_NODE_SETUP.md @@ -0,0 +1,295 @@ +# Integrated Blockchain Node Setup Guide + +## Overview + +This guide explains how to deploy the integrated blockchain node (with full mempool support) from scratch on any host or container. This is the recommended approach for production deployments. + +## Quick Start + +### Automated Setup + +```bash +# Run the deployment script +sudo bash /opt/aitbc/scripts/deployment/deploy-integrated-blockchain-node.sh +``` + +### Manual Setup + +See the step-by-step instructions below. + +## Prerequisites + +- **OS**: Debian 12+ or Ubuntu 22.04+ +- **Python**: 3.13+ +- **Git**: For cloning repository +- **Systemd**: For service management +- **PostgreSQL**: Optional, for mempool backend (can use SQLite) + +## Step-by-Step Setup + +### 1. Clone Repository + +```bash +sudo git clone https://gitea.bubuit.net:3000/oib/aitbc.git /opt/aitbc +cd /opt/aitbc +``` + +### 2. Setup Python Environment + +```bash +# Create virtual environment +sudo python3 -m venv /opt/aitbc/venv + +# Activate and install dependencies +sudo /opt/aitbc/venv/bin/pip install -r apps/blockchain-node/requirements.txt +``` + +### 3. Create Runtime Directories + +```bash +sudo mkdir -p /var/lib/aitbc/keystore +sudo mkdir -p /var/lib/aitbc/data +sudo mkdir -p /var/lib/aitbc/logs +sudo mkdir -p /etc/aitbc + +# Set permissions +sudo chmod 700 /var/lib/aitbc/keystore +sudo chmod 755 /var/lib/aitbc/data +sudo chmod 755 /var/lib/aitbc/logs +sudo chmod 755 /etc/aitbc +``` + +### 4. Create Environment Files + +**Blockchain Configuration (`/etc/aitbc/blockchain.env`):** +```bash +sudo nano /etc/aitbc/blockchain.env +``` + +```env +# Blockchain Node Configuration +CHAIN_ID=ait-mainnet +RPC_BIND_HOST=0.0.0.0 +RPC_BIND_PORT=8006 +P2P_BIND_HOST=0.0.0.0 +P2P_BIND_PORT=8001 +ENABLE_BLOCK_PRODUCTION=false +GOSSIP_BROADCAST_URL=redis://127.0.0.1:6379 +CROSS_SITE_REMOTE_ENDPOINTS= +``` + +**Node Configuration (`/etc/aitbc/node.env`):** +```bash +sudo nano /etc/aitbc/node.env +``` + +```env +# Node Configuration +NODE_ID=$(hostname) +ISLAND_ID=default-island +CHAIN_ID=ait-mainnet +NODE_ROLE=follower +P2P_BIND_PORT=8001 +``` + +### 5. Setup Systemd Service + +```bash +sudo nano /etc/systemd/system/aitbc-blockchain-node.service +``` + +```ini +[Unit] +Description=AITBC Production Blockchain Node +After=network.target postgresql.service + +[Service] +Type=simple +User=root +WorkingDirectory=/opt/aitbc +Environment="PATH=/opt/aitbc/venv/bin:/usr/local/sbin:/usr/local/bin:/usr/sbin:/usr/bin" +EnvironmentFile=/etc/aitbc/blockchain.env +EnvironmentFile=/etc/aitbc/node.env +ExecStartPre=/opt/aitbc/scripts/utils/load-keystore-secrets.sh +ExecStart=/opt/aitbc/venv/bin/python -m aitbc_chain.main +Restart=always +RestartSec=10 +StandardOutput=journal +StandardError=journal + +[Install] +WantedBy=multi-user.target +``` + +### 6. Start Service + +```bash +# Reload systemd +sudo systemctl daemon-reload + +# Enable service +sudo systemctl enable aitbc-blockchain-node + +# Start service +sudo systemctl start aitbc-blockchain-node +``` + +### 7. Verify Deployment + +```bash +# Check service status +sudo systemctl status aitbc-blockchain-node + +# Check RPC endpoint +curl http://localhost:8006/rpc/head + +# Check mempool endpoint +curl http://localhost:8006/rpc/mempool +``` + +## Container Deployment + +### For incus Containers + +```bash +# Create container +incus launch ubuntu:22.04 aitbc-container + +# Push repository to container +incus file push -r /opt/aitbc aitbc-container/opt/ + +# Run setup inside container +incus exec aitbc-container -- bash /opt/aitbc/scripts/deployment/deploy-integrated-blockchain-node.sh +``` + +### For Docker + +```bash +# Build image +docker build -t aitbc-blockchain-node -f docker/blockchain/Dockerfile . + +# Run container +docker run -d \ + --name aitbc-blockchain \ + -p 8006:8006 \ + -p 8001:8001 \ + -v /var/lib/aitbc:/var/lib/aitbc \ + -v /etc/aitbc:/etc/aitbc \ + aitbc-blockchain-node +``` + +## Configuration + +### Enable Block Production + +Edit `/etc/aitbc/blockchain.env`: +```env +ENABLE_BLOCK_PRODUCTION=true +``` + +Then restart: +```bash +sudo systemctl restart aitbc-blockchain-node +``` + +### Configure Mempool Backend + +**PostgreSQL (Recommended):** +```env +MEMPOOL_BACKEND=database +MEMPOOL_DB_URL=postgresql+psycopg://aitbc_mempool:password@localhost:5432/aitbc_mempool +``` + +**SQLite (Default):** +```env +MEMPOOL_BACKEND=database +``` + +### Configure Cross-Site Sync + +```env +CROSS_SITE_REMOTE_ENDPOINTS=https://aitbc.bubuit.net/rpc,https://aitbc1.bubuit.net/rpc +``` + +## Management + +### Service Management + +```bash +# Status +sudo systemctl status aitbc-blockchain-node + +# Restart +sudo systemctl restart aitbc-blockchain-node + +# Stop +sudo systemctl stop aitbc-blockchain-node + +# Logs +sudo journalctl -u aitbc-blockchain-node -f +``` + +### Update Node + +```bash +cd /opt/aitbc +sudo git pull origin main +sudo systemctl restart aitbc-blockchain-node +``` + +## Troubleshooting + +### Service Won't Start + +```bash +# Check logs +sudo journalctl -u aitbc-blockchain-node -n 50 --no-pager + +# Check configuration +sudo /opt/aitbc/venv/bin/python -m aitbc_chain.main --check-config +``` + +### Port Already in Use + +```bash +# Find process using port +sudo lsof -i :8006 + +# Kill process +sudo kill -9 +``` + +### Mempool Endpoint Not Working + +```bash +# Check if mempool backend is configured +grep MEMPOOL_BACKEND /etc/aitbc/blockchain.env + +# Verify database connection +sudo -u postgres psql -d aitbc_mempool -c "SELECT 1" +``` + +## Migration from Standalone Node + +See [Blockchain Node Implementation Guide](../blockchain/IMPLEMENTATION_GUIDE.md) for detailed migration instructions. + +## Agent Deployment + +For automated deployment using hermes agents, see the agent workflow in [/.windsurf/workflows/](/.windsurf/workflows/). + +## Verification Checklist + +- [ ] Service is running: `systemctl is-active aitbc-blockchain-node` +- [ ] RPC endpoint accessible: `curl http://localhost:8006/rpc/head` +- [ ] Mempool endpoint accessible: `curl http://localhost:8006/rpc/mempool` +- [ ] P2P listening on port 8001 +- [ ] No errors in logs: `journalctl -u aitbc-blockchain-node -n 100` +- [ ] Configuration files exist: `/etc/aitbc/blockchain.env`, `/etc/aitbc/node.env` +- [ ] Runtime directories exist: `/var/lib/aitbc/keystore`, `/var/lib/aitbc/data`, `/var/lib/aitbc/logs` + +## Support + +For issues or questions: +- Check logs: `sudo journalctl -u aitbc-blockchain-node -f` +- Review configuration: `/etc/aitbc/blockchain.env` +- See [Implementation Guide](../blockchain/IMPLEMENTATION_GUIDE.md) diff --git a/scripts/deployment/deploy-integrated-blockchain-node.sh b/scripts/deployment/deploy-integrated-blockchain-node.sh new file mode 100755 index 00000000..bfa7d2c7 --- /dev/null +++ b/scripts/deployment/deploy-integrated-blockchain-node.sh @@ -0,0 +1,297 @@ +#!/bin/bash +# +# Integrated Blockchain Node Deployment Script +# Deploys the full-featured integrated blockchain node with mempool support +# This script sets up the node from scratch on a new host or container +# + +set -e + +# Colors for output +RED='\033[0;31m' +GREEN='\033[0;32m' +YELLOW='\033[1;33m' +NC='\033[0m' # No Color + +# Configuration +REPO_URL="https://gitea.bubuit.net:3000/oib/aitbc.git" +INSTALL_DIR="/opt/aitbc" +ENV_FILE="/etc/aitbc/blockchain.env" +NODE_ENV_FILE="/etc/aitbc/node.env" +SERVICE_NAME="aitbc-blockchain-node" + +# Functions +log_info() { + echo -e "${GREEN}[INFO]${NC} $1" +} + +log_warn() { + echo -e "${YELLOW}[WARN]${NC} $1" +} + +log_error() { + echo -e "${RED}[ERROR]${NC} $1" +} + +check_root() { + if [ "$EUID" -ne 0 ]; then + log_error "This script must be run as root" + exit 1 + fi +} + +check_prerequisites() { + log_info "Checking prerequisites..." + + # Check for required commands + for cmd in git python3 pip3 systemctl; do + if ! command -v $cmd &> /dev/null; then + log_error "Required command not found: $cmd" + exit 1 + fi + done + + # Check Python version + PYTHON_VERSION=$(python3 --version | cut -d' ' -f2 | cut -d'.' -f1,2) + REQUIRED_VERSION="3.13" + if [ "$(printf '%s\n' "$REQUIRED_VERSION" "$PYTHON_VERSION" | sort -V | head -n1)" != "$REQUIRED_VERSION" ]; then + log_error "Python $REQUIRED_VERSION+ required, found $PYTHON_VERSION" + exit 1 + fi + + log_info "Prerequisites check passed" +} + +clone_repository() { + log_info "Cloning AITBC repository..." + + if [ -d "$INSTALL_DIR" ]; then + log_warn "Directory $INSTALL_DIR already exists" + read -p "Remove and re-clone? (y/n) " -n 1 -r + echo + if [[ $REPLY =~ ^[Yy]$ ]]; then + rm -rf "$INSTALL_DIR" + else + log_info "Using existing installation" + return + fi + fi + + git clone "$REPO_URL" "$INSTALL_DIR" + cd "$INSTALL_DIR" + + log_info "Repository cloned successfully" +} + +setup_python_environment() { + log_info "Setting up Python environment..." + + cd "$INSTALL_DIR" + + # Create virtual environment + python3 -m venv venv + + # Activate virtual environment + source venv/bin/activate + + # Install dependencies + if [ -f "apps/blockchain-node/requirements.txt" ]; then + pip install -r apps/blockchain-node/requirements.txt + else + log_warn "No requirements.txt found, installing core dependencies" + pip install pydantic pydantic-settings fastapi uvicorn sqlalchemy psycopg2-binary + fi + + deactivate + + log_info "Python environment setup complete" +} + +setup_directories() { + log_info "Setting up directories..." + + # Create runtime directories + mkdir -p /var/lib/aitbc/keystore + mkdir -p /var/lib/aitbc/data + mkdir -p /var/lib/aitbc/logs + + # Create configuration directory + mkdir -p /etc/aitbc + + # Set permissions + chmod 700 /var/lib/aitbc/keystore + chmod 755 /var/lib/aitbc/data + chmod 755 /var/lib/aitbc/logs + chmod 755 /etc/aitbc + + log_info "Directories setup complete" +} + +setup_environment_files() { + log_info "Setting up environment files..." + + # Create blockchain.env if it doesn't exist + if [ ! -f "$ENV_FILE" ]; then + cat > "$ENV_FILE" << 'EOF' +# Blockchain Node Configuration +CHAIN_ID=ait-mainnet +RPC_BIND_HOST=0.0.0.0 +RPC_BIND_PORT=8006 +P2P_BIND_HOST=0.0.0.0 +P2P_BIND_PORT=8001 +ENABLE_BLOCK_PRODUCTION=false +GOSSIP_BROADCAST_URL=redis://127.0.0.1:6379 +CROSS_SITE_REMOTE_ENDPOINTS= +EOF + chmod 600 "$ENV_FILE" + log_info "Created $ENV_FILE" + else + log_info "$ENV_FILE already exists, skipping" + fi + + # Create node.env if it doesn't exist + if [ ! -f "$NODE_ENV_FILE" ]; then + cat > "$NODE_ENV_FILE" << 'EOF' +# Node Configuration +NODE_ID=$(hostname) +ISLAND_ID=default-island +CHAIN_ID=ait-mainnet +NODE_ROLE=follower +P2P_BIND_PORT=8001 +EOF + chmod 600 "$NODE_ENV_FILE" + log_info "Created $NODE_ENV_FILE" + else + log_info "$NODE_ENV_FILE already exists, skipping" + fi +} + +setup_systemd_service() { + log_info "Setting up systemd service..." + + SERVICE_FILE="/etc/systemd/system/${SERVICE_NAME}.service" + + cat > "$SERVICE_FILE" << EOF +[Unit] +Description=AITBC Production Blockchain Node +After=network.target postgresql.service + +[Service] +Type=simple +User=root +WorkingDirectory=$INSTALL_DIR +Environment="PATH=$INSTALL_DIR/venv/bin:/usr/local/sbin:/usr/local/bin:/usr/sbin:/usr/bin" +EnvironmentFile=$ENV_FILE +EnvironmentFile=$NODE_ENV_FILE +ExecStartPre=$INSTALL_DIR/scripts/utils/load-keystore-secrets.sh +ExecStart=$INSTALL_DIR/venv/bin/python -m aitbc_chain.main +Restart=always +RestartSec=10 +StandardOutput=journal +StandardError=journal + +[Install] +WantedBy=multi-user.target +EOF + + systemctl daemon-reload + systemctl enable $SERVICE_NAME + + log_info "Systemd service setup complete" +} + +start_service() { + log_info "Starting blockchain node service..." + + systemctl start $SERVICE_NAME + + # Wait for service to start + sleep 5 + + if systemctl is-active --quiet $SERVICE_NAME; then + log_info "Service started successfully" + else + log_error "Service failed to start" + systemctl status $SERVICE_NAME --no-pager + exit 1 + fi +} + +verify_deployment() { + log_info "Verifying deployment..." + + # Check service status + if systemctl is-active --quiet $SERVICE_NAME; then + log_info "✓ Service is running" + else + log_error "✗ Service is not running" + exit 1 + fi + + # Check RPC endpoint + if curl -s http://localhost:8006/rpc/head > /dev/null; then + log_info "✓ RPC endpoint is accessible" + else + log_error "✗ RPC endpoint is not accessible" + exit 1 + fi + + # Check mempool endpoint + if curl -s http://localhost:8006/rpc/mempool > /dev/null; then + log_info "✓ Mempool endpoint is accessible" + else + log_error "✗ Mempool endpoint is not accessible" + exit 1 + fi + + log_info "Deployment verification complete" +} + +print_summary() { + echo "" + echo "==========================================" + echo " Integrated Blockchain Node Deployed" + echo "==========================================" + echo "" + echo "Service: $SERVICE_NAME" + echo "Install Dir: $INSTALL_DIR" + echo "Config: $ENV_FILE" + echo "" + echo "RPC Endpoints:" + echo " - Head: http://localhost:8006/rpc/head" + echo " - Mempool: http://localhost:8006/rpc/mempool" + echo "" + echo "Management Commands:" + echo " - Status: systemctl status $SERVICE_NAME" + echo " - Restart: systemctl restart $SERVICE_NAME" + echo " - Logs: journalctl -u $SERVICE_NAME -f" + echo "" + echo "Configuration:" + echo " - Edit config: nano $ENV_FILE" + echo " - After edit: systemctl restart $SERVICE_NAME" + echo "" +} + +# Main execution +main() { + echo "==========================================" + echo " Integrated Blockchain Node Deployment" + echo "==========================================" + echo "" + + check_root + check_prerequisites + clone_repository + setup_python_environment + setup_directories + setup_environment_files + setup_systemd_service + start_service + verify_deployment + print_summary + + log_info "Deployment completed successfully!" +} + +# Run main function +main "$@"