docs: Fix Update setup and upgrade guides

[dohernandez]

Fix setup guide for v0.4.0

Update setup and upgrade guides with additional setup requirements and instructions

Summary by CodeRabbit

• Documentation
  • Updated validator setup guide with new Python package prerequisites, revised node software extraction using versioned directories, and updated GenVM setup procedure.
  • Enhanced upgrade guide with keystore file migration instructions to ensure smooth transitions between validator versions.

_{✏️ Tip: You can customize this high-level summary in your review settings.}

[netlify]

✅ Deploy Preview for genlayer-docs ready!

Name	Link
🔨 Latest commit	7c533cf
🔍 Latest deploy log	https://app.netlify.com/projects/genlayer-docs/deploys/6932daab749dbc00086315f7
😎 Deploy Preview	https://deploy-preview-311--genlayer-docs.netlify.app
📱 Preview on mobile	Toggle QR Code... Use your smartphone camera to open QR code link.

---

To edit notification comments on pull requests, go to your Netlify project configuration.

[coderabbitai]

Walkthrough

Updates validator documentation to add Python prerequisites for GenVM setup, implement versioned directory structure for node software extraction, replace binary-based GenVM setup with Python script invocation, and add keystore file migration steps during version upgrades.

Changes

Cohort / File(s)	Summary
Setup Guide Enhancements pages/validators/setup-guide.mdx	Added Python prerequisites (python3, python3-pip, python3-venv); implemented versioned directory structure for node extraction; replaced binary GenVM setup with Python script invocation
Upgrade Guide Enhancements pages/validators/upgrade.mdx	Added keystore file migration steps (mkdir and cp commands) in two locations: v0.4 section and v0.3.8 Configuration Change section to preserve keystore data during upgrades

Estimated code review effort

🎯 2 (Simple) | ⏱️ ~8 minutes

• Verify keystore directory paths and copy commands are consistent across both occurrences in upgrade.mdx
• Confirm Python script path and GenVM setup syntax are correct and accessible

Possibly related PRs

• #239: Overlaps on GenVM setup modifications and versioned node extraction directory handling in setup-guide.mdx
• #221: Shares keystore-copy instructions and upgrade/setup procedure updates across validator docs
• #308: Overlaps on GenVM setup command changes and keystore migration logic in both setup and upgrade guides

Suggested reviewers

• AgustinRamiroDiaz
• cristiam86

Poem

🐰 Hop, hop! The setup's now versioned with care,
Python scripts dancing through GenVM's air,
Keystores migrate when upgrades take flight,
Documentation clean, installation just right! ✨

Pre-merge checks and finishing touches

❌ Failed checks (2 inconclusive)

Check name	Status	Explanation	Resolution
Title check	❓ Inconclusive	The title is partially related to the changeset but lacks clarity and specificity. It uses imprecise language ('Fix Update') and doesn't clearly convey the main changes, which involve adding prerequisites, versioned directory handling, and keystore file copying instructions.	Use clearer, more specific language following the Conventional Commits format. Consider: 'docs(validators): add v0.4 setup prerequisites and upgrade keystore migration steps' to better reflect the actual changes made.
Description check	❓ Inconclusive	The description is vague and incomplete. It mentions updating guides with 'additional setup requirements and instructions' but lacks specific details about what was changed. It does not follow the Conventional Commits format and omits concrete examples of the modifications.	Expand the description with specific details: list the new prerequisites (python3, python3-pip, python3-venv), explain the versioned directory structure changes, and describe the keystore migration steps added in the upgrade guide.

✅ Passed checks (1 passed)

Check name	Status	Explanation
Docstring Coverage	✅ Passed	No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check.

✨ Finishing touches

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Post copyable unit tests in a comment
• Commit unit tests in branch docs/node/fix-v0.4

---

📜 Recent review details

Configuration used: CodeRabbit UI

Review profile: CHILL

Plan: Pro

📥 Commits

Reviewing files that changed from the base of the PR and between 5a87a11 and 7c533cf.

📒 Files selected for processing (2)

• pages/validators/setup-guide.mdx (2 hunks)
• pages/validators/upgrade.mdx (1 hunks)

🧰 Additional context used

📓 Path-based instructions (2)

pages/**/*.mdx

📄 CodeRabbit inference engine (CLAUDE.md)

pages/**/*.mdx: All content is in MDX format supporting React components
Import and use custom components within MDX files
Create .mdx file in appropriate pages/ subdirectory when adding new pages
All content should support React components in MDX files

Files:

• pages/validators/upgrade.mdx
• pages/validators/setup-guide.mdx

pages/validators/setup-guide.mdx

📄 CodeRabbit inference engine (CLAUDE.md)

pages/validators/setup-guide.mdx: Setup Guide Updates (pages/validators/setup-guide.mdx): Update version references in download examples and version lists, update configuration examples with new contract addresses when applicable, enhance command documentation when new features are added to existing commands, update genesis block configuration in consensus section when network upgrades occur
Consensus contract addresses change with network upgrades and must be updated in configuration examples
Genesis block numbers are specified for faster node startup (optional but recommended) and should be updated in documentation when network upgrades occur
GenVM diagnostics integration affects the doctor command behavior and should be documented in the validator setup guide
Update version references in download examples and version lists in setup-guide.mdx when new validator releases occur
Update configuration examples with new contract addresses in setup-guide.mdx when applicable
Enhance command documentation in setup-guide.mdx when new features are added to existing commands
Update genesis block configuration in consensus section of setup-guide.mdx when network upgrades occur
Update consensus contract addresses and genesis block number in setup-guide.mdx when network upgrades occur
Enhance command documentation in setup-guide.mdx when new features are added to existing commands
Update version list in curl command output example (line ~88), download command version variable (line ~113), consensus contract addresses and genesis block number (lines ~143-146), and command documentation (line ~347) in setup-guide.mdx for new validator releases

Files:

• pages/validators/setup-guide.mdx

🧠 Learnings (13)

📓 Common learnings

Learnt from: CR
Repo: genlayerlabs/genlayer-docs PR: 0
File: CLAUDE.md:0-0
Timestamp: 2025-07-24T07:56:58.272Z
Learning: Applies to pages/validators/setup-guide.mdx : Setup Guide Updates (pages/validators/setup-guide.mdx): Update version references in download examples and version lists, update configuration examples with new contract addresses when applicable, enhance command documentation when new features are added to existing commands, update genesis block configuration in consensus section when network upgrades occur

Learnt from: CR
Repo: genlayerlabs/genlayer-docs PR: 0
File: CLAUDE.md:0-0
Timestamp: 2025-07-24T07:56:58.272Z
Learning: Applies to pages/validators/setup-guide.mdx : Update genesis block configuration in consensus section of setup-guide.mdx when network upgrades occur

Learnt from: CR
Repo: genlayerlabs/genlayer-docs PR: 0
File: CLAUDE.md:0-0
Timestamp: 2025-07-24T07:56:58.272Z
Learning: Applies to pages/validators/setup-guide.mdx : Update version list in curl command output example (line ~88), download command version variable (line ~113), consensus contract addresses and genesis block number (lines ~143-146), and command documentation (line ~347) in setup-guide.mdx for new validator releases

Learnt from: CR
Repo: genlayerlabs/genlayer-docs PR: 0
File: CLAUDE.md:0-0
Timestamp: 2025-07-24T07:56:58.272Z
Learning: Applies to pages/validators/setup-guide.mdx : GenVM diagnostics integration affects the doctor command behavior and should be documented in the validator setup guide

Learnt from: CR
Repo: genlayerlabs/genlayer-docs PR: 0
File: CLAUDE.md:0-0
Timestamp: 2025-07-24T07:56:58.272Z
Learning: Applies to pages/validators/setup-guide.mdx : Update version references in download examples and version lists in setup-guide.mdx when new validator releases occur

Learnt from: CR
Repo: genlayerlabs/genlayer-docs PR: 0
File: CLAUDE.md:0-0
Timestamp: 2025-07-24T07:56:58.272Z
Learning: Applies to pages/validators/setup-guide.mdx : Genesis block numbers are specified for faster node startup (optional but recommended) and should be updated in documentation when network upgrades occur

Learnt from: dohernandez
Repo: genlayerlabs/genlayer-docs PR: 308
File: pages/validators/setup-guide.mdx:790-790
Timestamp: 2025-12-03T17:07:37.200Z
Learning: In pages/validators/setup-guide.mdx: When documenting docker-compose setup, users must create genvm-module-web-docker.yaml (separate from the tarball's genvm-module-web.yaml) to point the webdriver URL to the docker service name (http://webdriver-container:4444) instead of localhost, as the tarball version is configured for binary execution with localhost.

Learnt from: CR
Repo: genlayerlabs/genlayer-docs PR: 0
File: CLAUDE.md:0-0
Timestamp: 2025-07-24T07:56:58.272Z
Learning: Applies to pages/validators/setup-guide.mdx : Update consensus contract addresses and genesis block number in setup-guide.mdx when network upgrades occur

Learnt from: CR
Repo: genlayerlabs/genlayer-docs PR: 0
File: CLAUDE.md:0-0
Timestamp: 2025-07-24T07:56:58.272Z
Learning: Applies to pages/validators/setup-guide.mdx : Enhance command documentation in setup-guide.mdx when new features are added to existing commands

Learnt from: CR
Repo: genlayerlabs/genlayer-docs PR: 0
File: CLAUDE.md:0-0
Timestamp: 2025-07-24T07:56:58.272Z
Learning: Applies to pages/validators/setup-guide.mdx : Enhance command documentation in setup-guide.mdx when new features are added to existing commands

📚 Learning: 2025-07-24T07:56:58.272Z

Learnt from: CR
Repo: genlayerlabs/genlayer-docs PR: 0
File: CLAUDE.md:0-0
Timestamp: 2025-07-24T07:56:58.272Z
Learning: Applies to pages/validators/setup-guide.mdx : Setup Guide Updates (pages/validators/setup-guide.mdx): Update version references in download examples and version lists, update configuration examples with new contract addresses when applicable, enhance command documentation when new features are added to existing commands, update genesis block configuration in consensus section when network upgrades occur

Applied to files:

• pages/validators/upgrade.mdx
• pages/validators/setup-guide.mdx

📚 Learning: 2025-07-24T07:56:58.272Z

Learnt from: CR
Repo: genlayerlabs/genlayer-docs PR: 0
File: CLAUDE.md:0-0
Timestamp: 2025-07-24T07:56:58.272Z
Learning: Applies to pages/validators/setup-guide.mdx : Update genesis block configuration in consensus section of setup-guide.mdx when network upgrades occur

Applied to files:

• pages/validators/upgrade.mdx
• pages/validators/setup-guide.mdx

📚 Learning: 2025-07-24T07:56:58.272Z

Learnt from: CR
Repo: genlayerlabs/genlayer-docs PR: 0
File: CLAUDE.md:0-0
Timestamp: 2025-07-24T07:56:58.272Z
Learning: Applies to pages/validators/setup-guide.mdx : Update version list in curl command output example (line ~88), download command version variable (line ~113), consensus contract addresses and genesis block number (lines ~143-146), and command documentation (line ~347) in setup-guide.mdx for new validator releases

Applied to files:

• pages/validators/upgrade.mdx
• pages/validators/setup-guide.mdx

📚 Learning: 2025-07-24T07:56:58.272Z

Learnt from: CR
Repo: genlayerlabs/genlayer-docs PR: 0
File: CLAUDE.md:0-0
Timestamp: 2025-07-24T07:56:58.272Z
Learning: Applies to pages/validators/setup-guide.mdx : Update consensus contract addresses and genesis block number in setup-guide.mdx when network upgrades occur

Applied to files:

• pages/validators/upgrade.mdx
• pages/validators/setup-guide.mdx

📚 Learning: 2025-07-24T07:56:58.272Z

Learnt from: CR
Repo: genlayerlabs/genlayer-docs PR: 0
File: CLAUDE.md:0-0
Timestamp: 2025-07-24T07:56:58.272Z
Learning: Applies to pages/validators/setup-guide.mdx : Update configuration examples with new contract addresses in setup-guide.mdx when applicable

Applied to files:

• pages/validators/upgrade.mdx
• pages/validators/setup-guide.mdx

📚 Learning: 2025-07-24T07:56:58.272Z

Learnt from: CR
Repo: genlayerlabs/genlayer-docs PR: 0
File: CLAUDE.md:0-0
Timestamp: 2025-07-24T07:56:58.272Z
Learning: Applies to pages/validators/setup-guide.mdx : Update version references in download examples and version lists in setup-guide.mdx when new validator releases occur

Applied to files:

• pages/validators/upgrade.mdx
• pages/validators/setup-guide.mdx

📚 Learning: 2025-07-24T07:56:58.272Z

Learnt from: CR
Repo: genlayerlabs/genlayer-docs PR: 0
File: CLAUDE.md:0-0
Timestamp: 2025-07-24T07:56:58.272Z
Learning: Applies to pages/validators/setup-guide.mdx : Genesis block numbers are specified for faster node startup (optional but recommended) and should be updated in documentation when network upgrades occur

Applied to files:

• pages/validators/upgrade.mdx

📚 Learning: 2025-07-24T07:56:58.272Z

Learnt from: CR
Repo: genlayerlabs/genlayer-docs PR: 0
File: CLAUDE.md:0-0
Timestamp: 2025-07-24T07:56:58.272Z
Learning: Applies to pages/validators/setup-guide.mdx : Consensus contract addresses change with network upgrades and must be updated in configuration examples

Applied to files:

• pages/validators/upgrade.mdx

📚 Learning: 2025-07-24T07:56:58.272Z

Learnt from: CR
Repo: genlayerlabs/genlayer-docs PR: 0
File: CLAUDE.md:0-0
Timestamp: 2025-07-24T07:56:58.272Z
Learning: Applies to pages/validators/changelog.mdx : Changelog Updates (pages/validators/changelog.mdx): Add new version entries at the top in reverse chronological order, use consistent format: # v0.x.x, ## New features, ## Bug fixes, ## Misc, and include missing intermediate versions if needed

Applied to files:

• pages/validators/upgrade.mdx

📚 Learning: 2025-07-24T07:56:58.272Z

Learnt from: CR
Repo: genlayerlabs/genlayer-docs PR: 0
File: CLAUDE.md:0-0
Timestamp: 2025-07-24T07:56:58.272Z
Learning: Applies to pages/validators/setup-guide.mdx : Enhance command documentation in setup-guide.mdx when new features are added to existing commands

Applied to files:

• pages/validators/upgrade.mdx
• pages/validators/setup-guide.mdx

📚 Learning: 2025-07-24T07:56:58.272Z

Learnt from: CR
Repo: genlayerlabs/genlayer-docs PR: 0
File: CLAUDE.md:0-0
Timestamp: 2025-07-24T07:56:58.272Z
Learning: Applies to pages/validators/setup-guide.mdx : GenVM diagnostics integration affects the doctor command behavior and should be documented in the validator setup guide

Applied to files:

• pages/validators/setup-guide.mdx

📚 Learning: 2025-12-03T17:07:37.200Z

Learnt from: dohernandez
Repo: genlayerlabs/genlayer-docs PR: 308
File: pages/validators/setup-guide.mdx:790-790
Timestamp: 2025-12-03T17:07:37.200Z
Learning: In pages/validators/setup-guide.mdx: When documenting docker-compose setup, users must create genvm-module-web-docker.yaml (separate from the tarball's genvm-module-web.yaml) to point the webdriver URL to the docker service name (http://webdriver-container:4444) instead of localhost, as the tarball version is configured for binary execution with localhost.

Applied to files:

• pages/validators/setup-guide.mdx

🔇 Additional comments (7)

pages/validators/setup-guide.mdx (5)

160-160: Clarify necessity of Python package management tools in prerequisites.

The prerequisites list python3-pip and python3-venv, but these are typically only needed if setup.py explicitly uses package management or virtual environments. If the setup script is self-contained, these may be unnecessary system dependencies.

For clarity, please verify and document:

1. Does the GenVM setup.py script require pip or venv functionality?
2. Are these truly system prerequisites, or should they be listed only if users need to manage Python packages separately?

This affects user setup complexity on minimal systems. Based on learnings, ensure the documented prerequisites align exactly with v0.4.0 setup requirements.

---

207-209: Verify tar command syntax and shell variable handling.

Line 208 shows unusual backtick placement within the tar command. The syntax should clarify whether the entire filename is meant to use command substitution or if this is a markdown rendering artifact.

The intended command should be:

tar -xzvf genlayer-node-linux-amd64-${version}.tar.gz -C ./${version}

Please verify the actual shell command is correct, as backticks mid-command would cause syntax errors.

---

207-214: Versioned directory structure is well-integrated.

The changes to create a versioned directory (line 207) and navigate into it (line 213) are consistent with the PR's shift toward versioned installations. This approach supports side-by-side versions and cleaner upgrades.

Ensure documentation clearly conveys that users now have isolated version directories rather than single installation directories.

---

216-220: Python-based GenVM setup replaces binary execution.

The shift from a binary-based GenVM setup to python3 ./third_party/genvm/bin/setup.py is documented and aligns with the Python prerequisites added. This approach improves portability and maintainability.

Verify that the setup.py script handles all initialization that the previous binary setup provided, and that no additional manual GenVM configuration steps are now required post-execution.

---

586-591: GenVM diagnostics integration in doctor command is well-documented.

The doctor command documentation (lines 586-590) now includes comprehensive GenVM diagnostics validation covering consensus contracts, GenVM module connectivity, LLM provider config, and network configuration. This aligns with the learning that GenVM diagnostics should be documented in the validator setup guide.

This enhanced diagnostic capability supports the new Python-based GenVM setup flow.

pages/validators/upgrade.mdx (2)

37-42: Keystore migration steps align with versioned installation approach.

The added keystore migration instructions (lines 37-42) properly guide users to preserve their operator keys when upgrading to v0.4. The use of placeholder syntax (<path-to-old-installation>, <path-to-new-installation>) is clear and prevents path-related errors.

This step is essential given the shift to versioned directories and enables users to maintain their validator identity across versions.

---

14-42: v0.3.x → v0.4 upgrade section properly documents breaking changes and migration.

The section clearly communicates:

1. The breaking change (new consensus deployment, staking requirement)
2. Database reset requirement (removing data/node/genlayer.db)
3. The new owner/operator separation model
4. Keystore preservation strategy via migration steps

The integration of keystore migration aligns with the versioned directory structure introduced in setup-guide.mdx and supports continuity of validator identity.

Per learnings, ensure that all consensus contract addresses and genesis blocks documented here remain in sync with setup-guide.mdx when network upgrades occur.

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands and usage tips.}