ICN Version Upgrade Guide

This guide covers upgrading ICN between major, minor, and patch versions.

Versioning Scheme

MAJOR.MINOR.PATCH (e.g., 0.2.1)
MAJOR: Breaking changes (incompatible API changes)
MINOR: New features (backward-compatible)
PATCH: Bug fixes (backward-compatible)

Pre-Upgrade Checklist

Before upgrading any version:

Backup your data directory:

icnctl backup ~/icn-backup-$(date +%Y%m%d).tar.gz.age

Read the CHANGELOG: Check CHANGELOG.md for breaking changes
Check system requirements: Ensure your system meets new requirements
Plan maintenance window: Schedule downtime for node restart
Notify cooperative members: Let them know about upcoming downtime
Test on non-production node (if you have one)

Upgrade Methods

Method 1: Package Manager (Recommended)

If you installed via the installer script:

# Download and run upgrade script
curl -fsSL https://raw.githubusercontent.com/InterCooperative-Network/icn/main/scripts/upgrade.sh | bash

This will:

Download latest binaries
Stop icnd gracefully
Replace binaries
Restart icnd
Verify successful start

Method 2: Build from Source

For development or custom builds:

# 1. Backup
icnctl backup ~/icn-backup.tar.gz.age

# 2. Stop daemon
sudo systemctl stop icnd

# 3. Pull latest code
cd /path/to/icn
git fetch origin
git checkout v0.2.0  # Replace with desired version

# 4. Build
cd icn
cargo build --release

# 5. Install binaries
sudo cp target/release/{icnd,icnctl} /usr/local/bin/

# 6. Start daemon
sudo systemctl start icnd

# 7. Verify
icnctl --version
icnctl status

Method 3: Docker

# Pull latest image
docker pull icn/icnd:latest

# Restart container (preserves volume data)
docker-compose down
docker-compose up -d

# Verify
docker exec icn-node icnctl status

Version-Specific Upgrade Notes

v0.1.x → v0.2.x (Hypothetical)

Breaking Changes:

Protocol version bump (requires all nodes to upgrade)
RPC API changes (update client applications)

Migration Steps:

Backup data directory
Stop icnd
Upgrade binaries
Run migration tool (if provided):
```
icnctl migrate v0.2
```
Start icnd
Verify peers reconnect

Rollback Plan: If upgrade fails:

Stop icnd

Restore from backup:

icnctl restore ~/icn-backup.tar.gz.age --force

Downgrade binaries to v0.1.x
Restart icnd

Upgrade Scenarios

Patch Upgrade (e.g., 0.1.0 → 0.1.1)

Risk: Low Downtime: ~30 seconds Rollback: Easy

# 1. Backup (quick)
icnctl backup ~/icn-backup.tar.gz.age

# 2. Upgrade
sudo systemctl stop icnd
sudo cp /path/to/new/icnd /usr/local/bin/icnd
sudo systemctl start icnd

# 3. Verify
icnctl --version
journalctl -u icnd -f

Rollback:

sudo systemctl stop icnd
sudo cp /path/to/old/icnd /usr/local/bin/icnd
sudo systemctl start icnd

Minor Upgrade (e.g., 0.1.0 → 0.2.0)

Risk: Low-Medium Downtime: ~1-2 minutes Rollback: Moderate (may require data migration)

# 1. Backup
icnctl backup ~/icn-backup.tar.gz.age

# 2. Review CHANGELOG for breaking changes
cat CHANGELOG.md | grep -A 20 "## [0.2.0]"

# 3. Stop daemon
sudo systemctl stop icnd

# 4. Upgrade binaries
sudo cp /path/to/new/{icnd,icnctl} /usr/local/bin/

# 5. Run migration (if required)
icnctl migrate v0.2

# 6. Start daemon
sudo systemctl start icnd

# 7. Verify
icnctl status
icnctl network peers  # Check peer connectivity
icnctl ledger balance  # Check data integrity

Major Upgrade (e.g., 0.x.x → 1.0.0)

Risk: High Downtime: 5-15 minutes Rollback: Difficult (coordinate with network)

Requires coordination: All nodes in cooperative must upgrade together.

# 1. Coordinate with cooperative
# - Set upgrade date/time
# - Ensure all members are ready

# 2. Comprehensive backup
icnctl backup ~/icn-backup-major-upgrade.tar.gz.age
# Copy backup off-site!

# 3. Review upgrade guide
# Check docs/migration-guides/ for version-specific instructions

# 4. Stop daemon
sudo systemctl stop icnd

# 5. Upgrade binaries
sudo cp /path/to/new/{icnd,icnctl} /usr/local/bin/

# 6. Run migration tool
icnctl migrate v1.0 --verify

# 7. Start daemon
sudo systemctl start icnd

# 8. Extensive verification
icnctl status
icnctl network peers
icnctl ledger balance
icnctl trust list
icnctl gov domain list

# 9. Monitor for 24 hours
journalctl -u icnd -f

Post-Upgrade Verification

After any upgrade, verify:

1. Daemon Status

icnctl status
# Expected: Daemon running, no errors

2. Network Connectivity

icnctl network peers
# Expected: Peers reconnected within 30 seconds

3. Data Integrity

icnctl id show           # DID unchanged
icnctl ledger balance    # Balance correct
icnctl trust list        # Trust relationships intact
icnctl gov domain list   # Governance domains present

4. Logs

journalctl -u icnd -f
# Expected: No errors, normal operation

5. Metrics

curl http://localhost:9100/metrics | grep icn_network_connections_active
# Expected: > 0 connections

Rollback Procedures

Simple Rollback (Patch/Minor)

If new version has issues:

# 1. Stop new version
sudo systemctl stop icnd

# 2. Restore old binaries
sudo cp ~/icn-old-binaries/icnd /usr/local/bin/icnd

# 3. Restore data (if needed)
icnctl restore ~/icn-backup.tar.gz.age

# 4. Start old version
sudo systemctl start icnd

# 5. Verify
icnctl status

Complex Rollback (Major)

Requires network coordination:

Stop all nodes
Restore from backups taken before upgrade
Downgrade binaries on all nodes
Restart all nodes simultaneously
Verify network converges

Prevention: Test major upgrades on staging network first!

Multi-Node Cooperative Upgrades

Strategy 1: Rolling Upgrade (Minor versions)

Upgrade nodes one at a time:

Upgrade Node 1:
- Backup, stop, upgrade, start
- Verify peers reconnect
- Wait 5 minutes
Upgrade Node 2:
- Same process
- Wait 5 minutes
Continue until all nodes upgraded

Benefit: Zero downtime for cooperative Requirement: Backward-compatible protocol

Strategy 2: Coordinated Upgrade (Major versions)

All nodes upgrade simultaneously:

Pre-coordination:
- Set upgrade window (e.g., "Saturday 2 AM")
- All operators ready
- Backups taken
Upgrade:
- Stop all nodes at same time
- Upgrade binaries
- Start all nodes at same time
Verification:
- Nodes discover each other
- Gossip converges
- Ledger syncs

Benefit: Clean protocol version bump Downside: Requires downtime

Automated Upgrades

NOT RECOMMENDED for production cooperatives.

If you must automate:

#!/bin/bash
# /usr/local/bin/icn-auto-upgrade.sh

# Backup
icnctl backup /var/backups/icn/backup-$(date +%Y%m%d-%H%M%S).tar.gz.age

# Download latest
wget https://releases.icn.coop/latest/icnd -O /tmp/icnd.new
wget https://releases.icn.coop/latest/icnctl -O /tmp/icnctl.new

# Verify checksums
sha256sum -c /tmp/icn-checksums.txt || exit 1

# Stop daemon
systemctl stop icnd

# Upgrade
cp /tmp/icnd.new /usr/local/bin/icnd
cp /tmp/icnctl.new /usr/local/bin/icnctl
chmod +x /usr/local/bin/{icnd,icnctl}

# Start daemon
systemctl start icnd

# Verify
icnctl status || {
    # Rollback on failure
    systemctl stop icnd
    cp /usr/local/bin/icnd.backup /usr/local/bin/icnd
    systemctl start icnd
}

Better: Use monitoring and alerts, upgrade manually.

Troubleshooting

"Version mismatch" errors

Symptom: Peers disconnect after upgrade

Cause: Incompatible protocol versions

Solution:

Check all nodes upgraded to same version
Verify protocol version: icnctl network status
Coordinate upgrade if nodes out of sync

"Migration failed"

Symptom: Migration tool exits with error

Cause: Corrupted data or incompatible format

Solution:

Restore from backup
Review migration logs: journalctl -u icnd -b
Report bug with logs if persistent

"Daemon won't start after upgrade"

Symptom: icnd crashes on startup

Causes:

Incompatible data format
Missing migration step
Corrupted state

Solution:

Check logs: journalctl -u icnd -xe
Try migration tool: icnctl migrate v0.2
If failing, restore backup and rollback

"Ledger out of sync"

Symptom: Different balance on different nodes

Cause: Gossip not converged yet

Solution:

Wait 5-10 minutes for anti-entropy
Force sync: Restart daemon
Check gossip metrics: curl localhost:9100/metrics | grep gossip

Best Practices

Always backup before upgrading
Read CHANGELOG before major upgrades
Test on staging environment if possible
Schedule upgrades during low-activity periods
Monitor logs after upgrade for 24 hours
Keep old binaries until new version proven stable
Coordinate with cooperative for major upgrades
Document your upgrade process for your coop

Emergency Contacts

If upgrade fails and you need help:

GitHub Issues: https://github.com/InterCooperative-Network/icn/issues
Emergency rollback: Use backups (see Backup & Recovery)
Community support: Check community channels

ICN Version Upgrade Guide

Versioning Scheme

Pre-Upgrade Checklist

Upgrade Methods

Method 1: Package Manager (Recommended)

Method 2: Build from Source

Method 3: Docker

Version-Specific Upgrade Notes

v0.1.x → v0.2.x (Hypothetical)

Upgrade Scenarios

Patch Upgrade (e.g., 0.1.0 → 0.1.1)

Minor Upgrade (e.g., 0.1.0 → 0.2.0)

Major Upgrade (e.g., 0.x.x → 1.0.0)

Post-Upgrade Verification

1. Daemon Status

2. Network Connectivity

3. Data Integrity

4. Logs

5. Metrics

Rollback Procedures

Simple Rollback (Patch/Minor)

Complex Rollback (Major)

Multi-Node Cooperative Upgrades

Strategy 1: Rolling Upgrade (Minor versions)

Strategy 2: Coordinated Upgrade (Major versions)

Automated Upgrades

Troubleshooting

"Version mismatch" errors

"Migration failed"

"Daemon won't start after upgrade"

"Ledger out of sync"

Best Practices

Emergency Contacts

Related Documentation