Skip to content

docs: add comprehensive node migration and upgrade guide#3767

Open
HusseinAdeiza wants to merge 2 commits intotempoxyz:mainfrom
HusseinAdeiza:docs/add-moderato-migration-guide
Open

docs: add comprehensive node migration and upgrade guide#3767
HusseinAdeiza wants to merge 2 commits intotempoxyz:mainfrom
HusseinAdeiza:docs/add-moderato-migration-guide

Conversation

@HusseinAdeiza
Copy link
Copy Markdown

Summary

Adds comprehensive migration and upgrade documentation for node operators, addressing #2304.

Changes

  • Added docs/pages/guide/node/migration.mdx with complete upgrade procedures
  • 490 lines of comprehensive documentation
  • Covers binary updates, datadir management, and consensus configuration
  • Includes specific guides for T1C, T2, and Moderato network upgrades
  • Provides troubleshooting section with 7 common issues and solutions
  • Includes pre/during/post-upgrade checklists

Sections Included

Binary Version Management

Update procedures for all installation methods:

  • Installation script (tempoup)
  • Docker deployments
  • Source builds

Datadir Management

  • When to reset datadir (breaking changes, corruption, network migration)
  • Backup procedures before reset
  • Step-by-step reset process with snapshots

Network Upgrade Procedures

  • T1C Upgrade: Keychain signature migration (V1 → V2), precompile changes
  • T2 Upgrade: ValidatorConfig V2 migration, fee recipient onchain migration
  • Moderato Testnet: Testnet-specific upgrade best practices

Consensus Configuration

  • Default port reference (RPC, P2P, metrics)
  • Port configuration examples
  • Firewall configuration guide

Post-Migration Validation

  • Service status verification
  • Peer count checks
  • Sync status validation
  • Block height confirmation
  • Validator signing verification

Troubleshooting

Seven common migration issues with detailed solutions:

  1. Node won't start after upgrade
  2. Node stuck, not syncing
  3. Database corruption
  4. Validator not signing blocks
  5. Out of sync after network upgrade
  6. RPC connection refused
  7. Various configuration issues

Migration Checklist

Complete pre/during/post-upgrade workflow for operators.

Additional Resources

Links to changelog, system requirements, installation guides, Discord support, and GitHub.

Impact

This guide provides node operators with a single comprehensive resource for:

  • Safely upgrading through breaking changes
  • Understanding network upgrade requirements (T1C, T2, Moderato)
  • Troubleshooting common migration issues
  • Validating successful upgrades
  • Following best practices for node operations

Reduces support burden by addressing common questions in advance and providing operators with self-service troubleshooting steps.

Related

Addresses #2304

HusseinAdeiza and others added 2 commits April 30, 2026 09:12
Addresses tempoxyz#2304 by providing detailed migration documentation for node operators.

Key sections:
- Binary version management for all installation methods
- Datadir reset procedures and best practices
- Network upgrade guides (T1C, T2, Moderato)
- Consensus configuration and port management
- Post-migration validation procedures
- Comprehensive troubleshooting guide (7 common issues)
- Migration checklist for operators
- Additional resources and support channels

This guide helps validator and node operators safely upgrade through
breaking changes and network upgrades.
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant