Upgrade Guide - Fenine Network Documentation

Introduction

Keep your Fenine node updated to benefit from performance improvements, security patches, and new features. This guide covers safe upgrade procedures.

Always backup your node before upgrading. See Backup & Recovery guide.

Before You Upgrade

Check Current Version

fene-geth version

Output example:

Fene-Geth
Version: 1.2.5
Architecture: amd64
Protocol Versions: [65]
Network Id: 89

Review Release Notes

Check the GitHub releases page for:

New features
Breaking changes
Database migrations
Configuration updates
Known issues

Subscribe to releases on GitHub to get notifications about new versions.

Determine Upgrade Type

Upgrade Type	Description	Downtime	Risk
Patch (1.2.x → 1.2.y)	Bug fixes, minor improvements	<5 min	Low
Minor (1.x.0 → 1.y.0)	New features, optimizations	5-15 min	Medium
Major (x.0.0 → y.0.0)	Breaking changes, migrations	15-60 min	High
Hardfork	Network consensus change	Must upgrade before block height	Critical

Hardfork upgrades are mandatory and must be completed before the activation block height. Missing a hardfork will cause your node to reject new blocks.

Upgrade Procedures

Standard Upgrade
Major Upgrade
Hardfork Upgrade
Rollback

For patch and minor version upgrades:

1. Download New Version

cd /tmp

# Get latest version
LATEST_VERSION=$(curl -s https://api.github.com/repos/fenines-network/fene-geth/releases/latest | grep tag_name | cut -d '"' -f 4)

echo "Upgrading to: $LATEST_VERSION"

# Download
wget "https://github.com/fenines-network/fene-geth/releases/download/${LATEST_VERSION}/fene-geth-linux-amd64.tar.gz"

# Verify checksum
wget "https://github.com/fenines-network/fene-geth/releases/download/${LATEST_VERSION}/checksums.txt"
sha256sum -c checksums.txt

2. Backup Current Binary

sudo cp /usr/local/bin/fene-geth /usr/local/bin/fene-geth.backup

3. Stop Node

sudo systemctl stop fenine

# Verify stopped
sudo systemctl status fenine

4. Install New Binary

tar -xzf fene-geth-linux-amd64.tar.gz
sudo mv fene-geth /usr/local/bin/
sudo chmod +x /usr/local/bin/fene-geth

5. Verify Installation

fene-geth version

6. Start Node

sudo systemctl start fenine

# Monitor startup
sudo journalctl -u fenine -f

7. Verify Sync

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

Expected: {"result": false} (fully synced)

For major version upgrades with potential breaking changes:

1. Read Migration Guide

Check release notes for:

Database format changes
Configuration file updates
Deprecated flags
New requirements

2. Backup Everything

# Stop node
sudo systemctl stop fenine

# Backup data directory
sudo tar -czf /backup/fenine-data-$(date +%Y%m%d).tar.gz \
  /var/lib/fenine

# Backup config
sudo cp /var/lib/fenine/config.toml \
  /backup/config.toml.$(date +%Y%m%d)

3. Update Configuration

Review config changes in release notes:

sudo nano /var/lib/fenine/config.toml

Example changes for v2.0.0:

# Old format (v1.x)
[Eth]
SyncMode = "full"

# New format (v2.x)
[Eth.Sync]
Mode = "snap"  # New default
PivotBlockNumber = 0

4. Database Migration (if required)

Some upgrades require database migration:

# Run migration tool
fene-geth db migrate \
  --datadir /var/lib/fenine \
  --target-version 2.0

# This may take 30-60 minutes

5. Test Upgrade

# Start node in foreground to watch for errors
fene-geth --config /var/lib/fenine/config.toml

# Press Ctrl+C after 2-3 minutes if no errors

6. Start Service

sudo systemctl start fenine
sudo journalctl -u fenine -f

7. Monitor for Issues

Watch logs for 15-30 minutes:

No panic errors
Sync continues normally
Peer connections stable
Memory usage normal

Critical: Must complete before hardfork activation block.

Preparation (1 week before)

Announcement: Join Discord/Telegram for hardfork announcements
Timeline: Note activation block height
Testing: Test upgrade on testnet first

Upgrade Window

Complete upgrade at least 24 hours before activation:

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

# Compare to activation block in announcement
# Example: Hardfork activates at block 5,000,000
# Current block: 4,950,000
# Remaining: 50,000 blocks ≈ 41 hours

Upgrade Steps

# Download hardfork release
HARDFORK_VERSION="v2.0.0-hardfork"
wget "https://github.com/fenines-network/fene-geth/releases/download/${HARDFORK_VERSION}/fene-geth-linux-amd64.tar.gz"

# Verify checksum (critical for hardforks!)
sha256sum fene-geth-linux-amd64.tar.gz
# Compare with official announcement

# Standard upgrade process
sudo systemctl stop fenine
tar -xzf fene-geth-linux-amd64.tar.gz
sudo mv fene-geth /usr/local/bin/
sudo systemctl start fenine

# Verify version
fene-geth version | grep "Version"
# Should show hardfork version

Post-Hardfork Verification

# Monitor after activation block
sudo journalctl -u fenine -f

# Check for hardfork messages:
# "Hardfork activated at block 5000000"
# "New consensus rules applied"

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

If you miss a hardfork, your node will fork from the network. You’ll need to re-sync from a checkpoint after the hardfork block.

If upgrade fails, rollback to previous version:

1. Stop Failed Node

sudo systemctl stop fenine

2. Restore Backup Binary

sudo mv /usr/local/bin/fene-geth.backup \
  /usr/local/bin/fene-geth

3. Restore Configuration (if changed)

sudo cp /backup/config.toml.YYYYMMDD \
  /var/lib/fenine/config.toml

4. Restore Database (if corrupted)

sudo systemctl stop fenine

# Remove corrupted data
sudo rm -rf /var/lib/fenine/geth

# Restore from backup
sudo tar -xzf /backup/fenine-data-YYYYMMDD.tar.gz \
  -C /

5. Start Node

sudo systemctl start fenine
sudo journalctl -u fenine -f

6. Report Issue

Open GitHub issue with:

Version numbers (old and new)
Error logs
System specs
Upgrade steps taken

Zero-Downtime Upgrade (Advanced)

For production RPC services, use multiple nodes:

Setup

Load Balancer: nginx or HAProxy distributing traffic
Node Pool: 2+ nodes behind load balancer

Rolling Upgrade

# Node 1: Remove from load balancer
# In nginx config, comment out node1

# Upgrade node1
ssh node1
sudo systemctl stop fenine
# ... upgrade steps ...
sudo systemctl start fenine

# Verify node1 healthy
curl http://node1:8545 -X POST \
  -d '{"jsonrpc":"2.0","method":"eth_blockNumber","params":[],"id":1}'

# Add node1 back to load balancer

# Wait 5 minutes, then repeat for node2, node3, etc.

Automated Upgrade Monitoring

Create /usr/local/bin/check-upgrade.sh:

#!/bin/bash

CURRENT_VERSION=$(fene-geth version | grep Version | awk '{print $2}')
LATEST_VERSION=$(curl -s https://api.github.com/repos/fenines-network/fene-geth/releases/latest | grep tag_name | cut -d '"' -f 4)

if [ "$CURRENT_VERSION" != "${LATEST_VERSION:1}" ]; then
  echo "New version available: $LATEST_VERSION (current: $CURRENT_VERSION)"
  echo "New Fenine version available: $LATEST_VERSION" | \
    mail -s "Node Upgrade Available" your-email@example.com
fi

Add to cron:

crontab -e

# Check for updates weekly
0 9 * * 1 /usr/local/bin/check-upgrade.sh

Upgrade Checklist

Common Upgrade Issues

Node won't start after upgrade

Symptoms: Service fails to start, immediate exitCauses:

Incompatible configuration
Missing permissions
Database corruption

Solutions:

# Check logs
sudo journalctl -u fenine -n 100

# Test config
fene-geth --config /var/lib/fenine/config.toml --help

# Verify permissions
sudo chown -R $USER:$USER /var/lib/fenine

# Reset database (last resort)
sudo systemctl stop fenine
sudo rm -rf /var/lib/fenine/geth
fene-geth init /var/lib/fenine/genesis.json --datadir /var/lib/fenine
sudo systemctl start fenine

Sync stuck after upgrade

Symptoms: Block height not increasingSolutions:

# Check peers
curl -X POST http://localhost:8545 \
  -d '{"jsonrpc":"2.0","method":"net_peerCount","params":[],"id":1}'

# If peer count low, add bootnodes
sudo systemctl stop fenine

# Add --bootnodes flag to systemd service
sudo nano /etc/systemd/system/fenine.service

ExecStart=/usr/local/bin/fene-geth \
  --config /var/lib/fenine/config.toml \
  --bootnodes "enode://[BOOTNODE]@bootnode1.fene.app:30303"

sudo systemctl daemon-reload
sudo systemctl start fenine

High memory usage after upgrade

Symptoms: OOM kills, swap usageSolutions:

# Reduce cache size
sudo systemctl stop fenine

# Edit service file
sudo nano /etc/systemd/system/fenine.service

# Change --cache 4096 to --cache 2048

sudo systemctl daemon-reload
sudo systemctl start fenine

# Monitor memory
watch free -h

Database migration failed

Symptoms: Migration script errorsSolutions:

# Restore from backup
sudo systemctl stop fenine
sudo rm -rf /var/lib/fenine/geth
sudo tar -xzf /backup/fenine-data-YYYYMMDD.tar.gz -C /

# Try migration again with more logging
fene-geth db migrate \
  --datadir /var/lib/fenine \
  --target-version 2.0 \
  --verbosity 5

Support Resources

Release Notes

View all version changes

Discord #node-operators

Get upgrade help

Troubleshooting

Fix common issues

Backup Guide

Protect your data

Upgrade Strategy:

Testnet first: Always test on testnet before mainnet
Off-peak hours: Upgrade during low traffic
Staged rollout: For multiple nodes, upgrade one at a time
Monitor closely: Watch for 30+ minutes post-upgrade

​Introduction

​Before You Upgrade

​Check Current Version

​Review Release Notes

​Determine Upgrade Type

​Upgrade Procedures

​1. Download New Version

​2. Backup Current Binary

​3. Stop Node

​4. Install New Binary

​5. Verify Installation

​6. Start Node

​7. Verify Sync

​1. Read Migration Guide

​2. Backup Everything

​3. Update Configuration

​4. Database Migration (if required)

​5. Test Upgrade

​6. Start Service

​7. Monitor for Issues

​Preparation (1 week before)

​Upgrade Window

​Upgrade Steps

​Post-Hardfork Verification

​1. Stop Failed Node

​2. Restore Backup Binary

​3. Restore Configuration (if changed)

​4. Restore Database (if corrupted)

​5. Start Node

​6. Report Issue

​Zero-Downtime Upgrade (Advanced)

​Setup

​Rolling Upgrade

​Automated Upgrade Monitoring

​Upgrade Checklist

​Common Upgrade Issues

​Support Resources

Release Notes

Discord #node-operators

Troubleshooting

Backup Guide

Introduction

Before You Upgrade

Check Current Version

Review Release Notes

Determine Upgrade Type

Upgrade Procedures

1. Download New Version

2. Backup Current Binary

3. Stop Node

4. Install New Binary

5. Verify Installation

6. Start Node

7. Verify Sync

1. Read Migration Guide

2. Backup Everything

3. Update Configuration

4. Database Migration (if required)

5. Test Upgrade

6. Start Service

7. Monitor for Issues

Preparation (1 week before)

Upgrade Window

Upgrade Steps

Post-Hardfork Verification

1. Stop Failed Node

2. Restore Backup Binary

3. Restore Configuration (if changed)

4. Restore Database (if corrupted)

5. Start Node

6. Report Issue

Zero-Downtime Upgrade (Advanced)

Setup

Rolling Upgrade

Automated Upgrade Monitoring

Upgrade Checklist

Common Upgrade Issues

Support Resources