Skip to content

SETUP_GUIDE.md

Latest commit

 

History

History
430 lines (324 loc) · 8.04 KB

SETUP_GUIDE.md

File metadata and controls

430 lines (324 loc) · 8.04 KB

Beacon Setup Guide

Complete guide for setting up Beacon gateway and mesh nodes.

Table of Contents

  1. Gateway Setup
  2. Mesh Node Setup
  3. Docker Deployment
  4. Production Deployment
  5. Monitoring

Gateway Setup

Prerequisites

  • Ubuntu 22.04 LTS or Debian 12
  • 4GB RAM, 2 CPU cores
  • 20GB SSD storage
  • Rust 1.75+

Installation

# Install Rust
curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh
source $HOME/.cargo/env

# Clone repository
git clone https://github.com/beacon-network/beacon-rpc.git
cd beacon-rpc

# Build gateway
cargo build --release --bin beacon-gateway

Configuration

Create gateway-config.toml:

listen_addr = "0.0.0.0:8545"
ws_addr = "0.0.0.0:8546"
network = "mainnet"
min_consensus = 2
query_peers = 3
request_timeout_secs = 5
cache_ttl_secs = 10

# Optional: Redis for caching
# redis_url = "redis://localhost:6379"

# Bootstrap nodes (use official Beacon bootstrap nodes)
bootstrap_nodes = [
    "/dns4/beacon-boot-1.ethereum.org/tcp/9001/p2p/16Uiu2HAm...",
    "/dns4/beacon-boot-2.ethereum.org/tcp/9001/p2p/16Uiu2HAm...",
]

Running

# Run with config file
./target/release/beacon-gateway --config gateway-config.toml

# Or with environment variables
RUST_LOG=info \
BEACON_LISTEN_ADDR=0.0.0.0:8545 \
BEACON_NETWORK=mainnet \
./target/release/beacon-gateway

Testing

# Check health
curl http://localhost:8545/health

# Test RPC
curl -X POST http://localhost:8545 \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","method":"eth_blockNumber","params":[],"id":1}'

Mesh Node Setup

Prerequisites

  • Ubuntu 22.04 LTS or Debian 12
  • 8GB RAM, 4 CPU cores (recommended)
  • 100GB SSD storage
  • Light client (Helios, Nimbus, or Lodestar)

Option 1: Setup with Helios

# 1. Install Helios light client
curl -L https://github.com/a16z/helios/releases/latest/download/helios-x86_64-unknown-linux-gnu \
  -o /usr/local/bin/helios
chmod +x /usr/local/bin/helios

# 2. Create Helios config
cat > helios-config.toml <<EOF
network = "mainnet"
consensus_rpc = "https://www.lightclientdata.org"
checkpoint = "0x..." # Get from https://eth-clients.github.io/checkpoint-sync-endpoints/
data_dir = "/var/lib/helios"
EOF

# 3. Start Helios
helios --config helios-config.toml --http 127.0.0.1:8000

# 4. Build Beacon mesh node
cd beacon-rpc
cargo build --release --bin beacon-mesh-node

# 5. Generate BLS key
mkdir -p /var/lib/beacon-mesh
./target/release/beacon-mesh-node keygen --output /var/lib/beacon-mesh/bls_key

# 6. Create mesh node config
cat > mesh-config.toml <<EOF
p2p_port = 9001
network = "mainnet"
client_type = "helios"
light_client_url = "http://127.0.0.1:8000"
data_dir = "/var/lib/beacon-mesh"
bls_key_path = "/var/lib/beacon-mesh/bls_key"

bootstrap_nodes = [
    "/dns4/beacon-boot-1.ethereum.org/tcp/9001/p2p/16Uiu2HAm...",
]
EOF

# 7. Start mesh node
./target/release/beacon-mesh-node --config mesh-config.toml

Option 2: Setup with Nimbus

# 1. Install Nimbus
sudo apt-get update
sudo apt-get install -y build-essential git

git clone https://github.com/status-im/nimbus-eth2.git
cd nimbus-eth2
make -j$(nproc) nimbus_beacon_node nimbus_light_client

# 2. Start Nimbus light client
./build/nimbus_light_client \
  --network=mainnet \
  --web3-url=ws://127.0.0.1:8001 \
  --trusted-block-root=0x... # Checkpoint

# 3. Configure Beacon mesh node with Nimbus
client_type = "nimbus"
light_client_url = "ws://127.0.0.1:8001"

Option 3: Setup with Lodestar

# 1. Install Node.js 18+
curl -fsSL https://deb.nodesource.com/setup_18.x | sudo -E bash -
sudo apt-get install -y nodejs

# 2. Install Lodestar
npm install -g @chainsafe/lodestar

# 3. Start Lodestar light client
lodestar beacon \
  --network mainnet \
  --checkpointSyncUrl https://beaconstate.info \
  --rest \
  --rest.port 8002

# 4. Configure Beacon mesh node with Lodestar
client_type = "lodestar"
light_client_url = "http://127.0.0.1:8002"

Docker Deployment

Docker Compose (Quickstart)

Create docker-compose.yml:

version: '3.8'

services:
  redis:
    image: redis:7-alpine
    ports:
      - "6379:6379"
    volumes:
      - redis-data:/data

  gateway:
    build:
      context: .
      dockerfile: Dockerfile.gateway
    ports:
      - "8545:8545"
      - "8546:8546"
    environment:
      - REDIS_URL=redis://redis:6379
      - NETWORK=mainnet
      - LOG_LEVEL=info
    depends_on:
      - redis
      - mesh-node-1
      - mesh-node-2

  mesh-node-1:
    build:
      context: .
      dockerfile: Dockerfile.mesh-node
    ports:
      - "9001:9001"
    environment:
      - CLIENT_TYPE=helios
      - NETWORK=mainnet
    volumes:
      - node1-data:/data

  mesh-node-2:
    build:
      context: .
      dockerfile: Dockerfile.mesh-node
    ports:
      - "9002:9001"
    environment:
      - CLIENT_TYPE=helios
      - NETWORK=mainnet
    volumes:
      - node2-data:/data

volumes:
  redis-data:
  node1-data:
  node2-data:

Run

# Start all services
docker-compose up -d

# Check logs
docker-compose logs -f gateway

# Test
curl http://localhost:8545/health

Production Deployment

AWS Deployment

Gateway (EC2 + ALB):

# 1. Launch EC2 instance (t3.medium, Ubuntu 22.04)
# 2. Install Beacon gateway (see above)
# 3. Configure systemd service

sudo cat > /etc/systemd/system/beacon-gateway.service <<EOF
[Unit]
Description=Beacon Gateway
After=network.target

[Service]
Type=simple
User=beacon
WorkingDirectory=/home/beacon/beacon-rpc
ExecStart=/home/beacon/beacon-rpc/target/release/beacon-gateway --config /etc/beacon/gateway-config.toml
Restart=always
RestartSec=10

[Install]
WantedBy=multi-user.target
EOF

sudo systemctl enable beacon-gateway
sudo systemctl start beacon-gateway

# 4. Setup Application Load Balancer
# - Target: EC2 instances on port 8545
# - Health check: /health
# - SSL certificate via ACM

Mesh Node (Multiple Regions):

# Deploy mesh nodes in different regions
# - us-east-1, eu-west-1, ap-southeast-1
# - Use t3.medium or similar
# - Ensure P2P ports (9001) are open

Cloudflare Setup

# 1. Point domain to ALB
beacon.example.com → ALB DNS

# 2. Enable Cloudflare proxy
# 3. Configure:
#    - SSL: Full (strict)
#    - DDoS protection: On
#    - Rate limiting: 100 req/s per IP
#    - Caching: Off (or very short TTL)

Monitoring

Prometheus Metrics

Gateway exposes metrics on /metrics:

# Request rate
beacon_rpc_requests_total{method="eth_getBalance"} 1234

# Response time
beacon_rpc_response_time_seconds{method="eth_call",quantile="0.95"} 0.432

# Consensus failures
beacon_consensus_failures_total 5

# Peer count
beacon_active_peers 47

Grafana Dashboard

Import dashboard: grafana-dashboard.json

Key Panels:

  • Request rate by method
  • P95 latency
  • Consensus success rate
  • Active peers
  • Error rate

Alerting

# Prometheus alerts
groups:
  - name: beacon
    rules:
      - alert: HighErrorRate
        expr: rate(beacon_rpc_errors_total[5m]) > 0.05
        for: 5m
        annotations:
          summary: "High error rate on Beacon gateway"

      - alert: LowPeerCount
        expr: beacon_active_peers < 3
        for: 10m
        annotations:
          summary: "Low peer count, may impact consensus"

Troubleshooting

Gateway won't start

# Check port availability
sudo lsof -i :8545

# Check logs
journalctl -u beacon-gateway -f

# Verify config
./beacon-gateway --config gateway-config.toml --check

No peers found

# Check bootstrap nodes
# Ensure P2P port is open (9001)
sudo ufw allow 9001/tcp

# Test connectivity
nc -zv beacon-boot-1.ethereum.org 9001

High latency

# Check mesh node health
curl http://localhost:9001/health

# Increase query_peers in config
query_peers = 5  # Default: 3

# Enable Redis caching
redis_url = "redis://localhost:6379"

Next Steps