# Temporary VM Deployment for Besu Nodes

This guide explains how to temporarily run all Besu nodes in a single VM before migrating to individual LXC containers. This approach is useful for:

- **Faster initial deployment** - Get the network running quickly
- **Easier testing and validation** - Single point of management
- **Simplified troubleshooting** - All nodes in one place
- **Flexible migration** - Move to LXC containers when ready

## Architecture

```
┌─────────────────────────────────────┐
│   Proxmox VE Host                  │
│                                     │
│   ┌─────────────────────────────┐  │
│   │  Temporary VM (VMID 9000)   │  │
│   │  IP: 192.168.11.90          │  │
│   │  Memory: 32GB, CPU: 8 cores │  │
│   │                               │  │
│   │  ┌─────────────────────────┐ │  │
│   │  │  Docker Network         │ │  │
│   │  │                          │ │  │
│   │  │  • 5 Validator Containers│ │  │
│   │  │  • 4 Sentry Containers  │ │  │
│   │  │  • 3 RPC Containers     │ │  │
│   │  └─────────────────────────┘ │  │
│   └─────────────────────────────┘  │
└─────────────────────────────────────┘
```

## Prerequisites

- Proxmox VE host with sufficient resources
- At least 32GB RAM available
- At least 500GB storage available
- Source project with keys and configuration: `/opt/smom-dbis-138`
- SSH access to Proxmox host

## Quick Start

### Step 1: Create the Temporary VM

On the Proxmox host:

```bash
cd /opt/smom-dbis-138-proxmox
sudo ./scripts/deployment/deploy-besu-temp-vm.sh
```

This will:
- Create a VM (VMID 9000) with Ubuntu 22.04
- Configure network (IP: 192.168.11.90)
- Install Docker and required tools
- Set up directory structure

**Note**: If the VM already exists, use `FORCE=true` to recreate it:

```bash
FORCE=true sudo ./scripts/deployment/deploy-besu-temp-vm.sh
```

### Step 2: Setup Docker and Copy Files

SSH into the VM and run the setup script:

```bash
# SSH into the VM
ssh root@192.168.11.90

# Run setup script (from inside the VM)
cd /opt/smom-dbis-138-proxmox
./scripts/deployment/setup-docker-besu.sh /opt/smom-dbis-138
```

This will:
- Install Docker and Docker Compose
- Create directory structure for all nodes
- Copy configuration files from source project
- Copy validator keys
- Copy genesis.json and permissions files

### Step 3: Copy Configuration Files

Copy the config templates to each node's directory:

```bash
# On the VM
cd /opt/besu

# Copy validator configs
for i in {1..5}; do
    cp /opt/smom-dbis-138-proxmox/templates/besu-configs/config-validator.toml \
       validators/validator-$i/config/config-validator.toml
done

# Copy sentry configs
for i in {1..4}; do
    cp /opt/smom-dbis-138-proxmox/templates/besu-configs/config-sentry.toml \
       sentries/sentry-$i/config/config-sentry.toml
done

# Copy RPC configs
for i in {1..3}; do
    cp /opt/smom-dbis-138-proxmox/templates/besu-configs/config-rpc.toml \
       rpc/rpc-$i/config/config-rpc.toml
done
```

### Step 4: Copy Keys

Ensure all node keys are in place:

```bash
# Validator keys should already be copied by setup script
# Verify they exist:
ls -la /opt/besu/validators/validator-*/keys/

# If keys are missing, copy them manually:
# (from source project on Proxmox host)
# scp -r /opt/smom-dbis-138/keys/validators/validator-* root@192.168.11.90:/opt/besu/validators/
```

### Step 5: Start Containers

```bash
cd /opt/besu
docker compose up -d
```

### Step 6: Verify Deployment

Check container status:

```bash
docker ps
docker compose logs -f
```

Run validation script (from Proxmox host):

```bash
cd /opt/smom-dbis-138-proxmox
./scripts/validation/validate-besu-temp-vm.sh
```

## Container Details

### Validators (5 nodes)
- **Containers**: `besu-validator-1` through `besu-validator-5`
- **P2P Ports**: 30303-30307
- **Metrics Ports**: 9545-9549
- **Memory**: 4GB each
- **Purpose**: QBFT consensus nodes

### Sentries (4 nodes)
- **Containers**: `besu-sentry-1` through `besu-sentry-4`
- **P2P Ports**: 30308-30311
- **Metrics Ports**: 9550-9553
- **Memory**: 2GB each
- **Purpose**: P2P relay and protection nodes

### RPC Nodes (3 nodes)
- **Containers**: `besu-rpc-1` through `besu-rpc-3`
- **HTTP RPC Ports**: 8545, 8547, 8549
- **WS RPC Ports**: 8546, 8548, 8550
- **P2P Ports**: 30312-30314
- **Metrics Ports**: 9554-9556
- **Memory**: 8GB each
- **Purpose**: Public RPC endpoints

## Management Commands

### View Logs

```bash
# All containers
docker compose logs -f

# Specific container
docker compose logs -f besu-validator-1

# Last 100 lines
docker compose logs --tail=100
```

### Restart Containers

```bash
# Restart all
docker compose restart

# Restart specific container
docker compose restart besu-validator-1
```

### Stop/Start Containers

```bash
# Stop all
docker compose stop

# Start all
docker compose start

# Stop specific container
docker compose stop besu-validator-1
```

### Check Status

```bash
# Container status
docker compose ps

# Resource usage
docker stats

# Health checks
docker compose ps --format "table {{.Name}}\t{{.Status}}"
```

## Monitoring

### Metrics Endpoints

Each container exposes Prometheus metrics:

- Validators: `http://192.168.11.90:9545-9549/metrics`
- Sentries: `http://192.168.11.90:9550-9553/metrics`
- RPC Nodes: `http://192.168.11.90:9554-9556/metrics`

### RPC Endpoints

RPC nodes expose JSON-RPC endpoints:

- RPC-1: `http://192.168.11.90:8545`
- RPC-2: `http://192.168.11.90:8547`
- RPC-3: `http://192.168.11.90:8549`

Test RPC:

```bash
curl -X POST -H "Content-Type: application/json" \
  --data '{"jsonrpc":"2.0","method":"eth_blockNumber","params":[],"id":1}' \
  http://192.168.11.90:8545
```

## Migration to LXC Containers

When ready to migrate to individual LXC containers:

### Step 1: Deploy LXC Containers

```bash
cd /opt/smom-dbis-138-proxmox
sudo ./scripts/deployment/deploy-besu-nodes.sh
```

This creates individual LXC containers for each node.

### Step 2: Run Migration Script

```bash
cd /opt/smom-dbis-138-proxmox
sudo ./scripts/migration/migrate-vm-to-lxc.sh /opt/smom-dbis-138
```

This script will:
- Export data from Docker containers
- Import data to LXC containers
- Copy configuration files
- Preserve all blockchain data

### Step 3: Verify Migration

```bash
# Check services in LXC containers
for vmid in 1000 1001 1002 1003 1004; do
    pct exec $vmid -- systemctl status besu-validator
done

# Start services if needed
for vmid in 1000 1001 1002 1003 1004; do
    pct exec $vmid -- systemctl start besu-validator
done
```

### Step 4: Shut Down Temporary VM

Once migration is verified:

```bash
# On Proxmox host
qm stop 9000
# Or delete if no longer needed:
# qm destroy 9000 --purge
```

## Troubleshooting

### Containers Won't Start

```bash
# Check logs
docker compose logs besu-validator-1

# Check configuration
docker exec besu-validator-1 cat /etc/besu/config-validator.toml

# Verify keys exist
docker exec besu-validator-1 ls -la /keys/
```

### Network Issues

```bash
# Check network connectivity
docker exec besu-validator-1 ping -c 3 8.8.8.8

# Check P2P port
netstat -tuln | grep 30303

# Check container network
docker network inspect besu-network
```

### Data Directory Issues

```bash
# Check disk space
df -h

# Check data directory permissions
ls -la /opt/besu/validators/validator-1/data/

# Check data size
du -sh /opt/besu/validators/validator-*/data/
```

### Performance Issues

```bash
# Check resource usage
docker stats

# Check system resources
htop

# Check disk I/O
iostat -x 1
```

## Configuration Files

### Location

- **Docker Compose**: `/opt/besu/docker-compose.yml`
- **Validator Configs**: `/opt/besu/validators/validator-{N}/config/config-validator.toml`
- **Sentry Configs**: `/opt/besu/sentries/sentry-{N}/config/config-sentry.toml`
- **RPC Configs**: `/opt/besu/rpc/rpc-{N}/config/config-rpc.toml`
- **Shared Files**: `/opt/besu/shared/genesis/` and `/opt/besu/shared/permissions/`

### Customization

Edit configuration files as needed:

```bash
# Edit validator config
vim /opt/besu/validators/validator-1/config/config-validator.toml

# Restart container to apply changes
docker compose restart besu-validator-1
```

## Backup

### Backup Data

```bash
# Create backup
tar czf /tmp/besu-backup-$(date +%Y%m%d).tar.gz /opt/besu

# Copy to Proxmox host
scp /tmp/besu-backup-*.tar.gz root@192.168.11.10:/opt/backups/
```

### Restore Data

```bash
# Copy backup to VM
scp root@192.168.11.10:/opt/backups/besu-backup-*.tar.gz /tmp/

# Extract
tar xzf /tmp/besu-backup-*.tar.gz -C /

# Restart containers
docker compose restart
```

## Security Considerations

- **Firewall**: Configure firewall rules on Proxmox host
- **SSH**: Use key-based authentication
- **Keys**: Protect validator keys - they control consensus
- **Network**: Use VLANs to isolate network traffic
- **Monitoring**: Set up alerts for container failures

## Next Steps

After successful deployment:

1. **Verify Network**: Ensure all nodes can communicate
2. **Check Consensus**: Verify validators are producing blocks
3. **Test RPC**: Test RPC endpoints with sample requests
4. **Monitor**: Set up monitoring and alerting
5. **Plan Migration**: Schedule migration to LXC containers when ready

## Support

For issues or questions:

1. Check logs: `docker compose logs`
2. Run validation: `./scripts/validation/validate-besu-temp-vm.sh`
3. Review configuration files
4. Check Proxmox host resources

## Related Documentation

- [Main Deployment Guide](DEPLOYMENT.md)
- [LXC Container Deployment](DEPLOYMENT_STEPS_COMPLETE.md)
- [Migration Guide](MIGRATION.md)
- [Troubleshooting Guide](TROUBLESHOOTING.md)

