Skip to content

doc: rewrite Nodes section#720

Open
gyrationtechs wants to merge 13 commits intomainfrom
doc/nodes-update
Open

doc: rewrite Nodes section#720
gyrationtechs wants to merge 13 commits intomainfrom
doc/nodes-update

Conversation

@gyrationtechs
Copy link
Copy Markdown
Contributor

@gyrationtechs gyrationtechs commented Mar 19, 2026

Summary

  • Rewrite the entire Nodes documentation section with clearer step-by-step instructions, replacing Docker-based setup guides with native binary installation workflows
  • Add a new Cardano node setup guide and expand the Cardano-db-sync guide with PostgreSQL setup, snapshot restoration, and performance tuning
  • Rewrite boot node, full node, RPC node, and node endpoints docs with tabbed UI for Preview/Preprod network selection
  • Add updated Insomnia API collection for node endpoints
  • Fix Vale CI workflow (permissions, file filter format, GITHUB_TOKEN) and resolve dark mode link color issues

Details

The Nodes documentation section has been rewritten to provide a more practical, end-to-end guide for operators setting up Midnight infrastructure. Each node type (Cardano node, Cardano-db-sync, Midnight full node, boot node, RPC node) now has a self-contained guide with prerequisites, installation steps, and verification commands. Network-specific configuration (Preview vs Preprod) uses Docusaurus tabs for clarity.

@vercel
Copy link
Copy Markdown

vercel bot commented Mar 19, 2026

The latest updates on your projects. Learn more about Vercel for GitHub.

Project Deployment Actions Updated (UTC)
midnight-wiki Error Error Apr 14, 2026 7:18pm

Request Review

@github-actions
Copy link
Copy Markdown

github-actions bot commented Mar 19, 2026

Summary

Status Count
🔍 Total 31
✅ Successful 9
⏳ Timeouts 0
🔀 Redirected 0
👻 Excluded 0
❓ Unknown 0
🚫 Errors 22
⛔ Unsupported 0

Errors per input

Errors in docs/nodes/boot-node.mdx

  • [ERROR] file:///home/runner/work/midnight-docs/midnight-docs/docs/nodes/cardano-db-sync | Cannot find file
  • [ERROR] file:///home/runner/work/midnight-docs/midnight-docs/docs/nodes/full-node#install-midnight-node | Cannot find file
  • [ERROR] file:///home/runner/work/midnight-docs/midnight-docs/docs/nodes/rpc-node | Cannot find file

Errors in docs/nodes/cardano-db-sync.mdx

Errors in docs/nodes/cardano-node.mdx

  • [ERROR] file:///home/runner/work/midnight-docs/midnight-docs/docs/nodes/cardano-db-sync | Cannot find file

Errors in docs/nodes/full-node.mdx

  • [ERROR] file:///home/runner/work/midnight-docs/midnight-docs/docs/nodes/cardano-db-sync | Cannot find file
  • [ERROR] file:///home/runner/work/midnight-docs/midnight-docs/docs/nodes/node-endpoints | Cannot find file
  • [ERROR] file:///home/runner/work/midnight-docs/midnight-docs/relnotes/support-matrix | Cannot find file

Errors in docs/nodes/index.mdx

  • [ERROR] file:///home/runner/work/midnight-docs/midnight-docs/docs/nodes/boot-node | Cannot find file
  • [ERROR] file:///home/runner/work/midnight-docs/midnight-docs/docs/nodes/full-node | Cannot find file
  • [ERROR] file:///home/runner/work/midnight-docs/midnight-docs/docs/nodes/full-node#full-node-vs-archive-node | Cannot find file
  • [ERROR] file:///home/runner/work/midnight-docs/midnight-docs/docs/nodes/rpc-node | Cannot find file

Errors in docs/nodes/node-endpoints.mdx

Errors in docs/nodes/rpc-node.mdx

  • [ERROR] file:///home/runner/work/midnight-docs/midnight-docs/docs/nodes/cardano-db-sync | Cannot find file
  • [ERROR] file:///home/runner/work/midnight-docs/midnight-docs/docs/nodes/full-node#install-midnight-node | Cannot find file
  • [ERROR] file:///home/runner/work/midnight-docs/midnight-docs/docs/nodes/node-endpoints | Cannot find file
    Full Github Actions output

@github-actions
Copy link
Copy Markdown

github-actions bot commented Mar 19, 2026

🚀 Preview Deployment

Deployment Ready

🔗 Preview URL: https://pr-720-midnight-docs.vercel.app

📝 Latest commit: d70a8e1
Updated: Apr 14, 2026, 7:24 PM UTC


This preview updates automatically when you push new commits to this PR.

@gyrationtechs gyrationtechs marked this pull request as ready for review March 20, 2026 12:46
@gyrationtechs gyrationtechs requested review from a team as code owners March 20, 2026 12:46
Copy link
Copy Markdown

@github-actions github-actions bot left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Remaining comments which cannot be posted as a review comment to avoid GitHub Rate Limit

vale

docs/nodes/full-node.mdx|197 col 4| [Midnight.HeadingSentenceCase] 'Verify the node' should be in sentence case.
docs/nodes/index.mdx|19 col 44| [Vale.Spelling] Did you really mean 'permissioned'?
docs/nodes/index.mdx|20 col 23| [Vale.Spelling] Did you really mean 'Mainchain'?
docs/nodes/index.mdx|24 col 12| [Vale.Spelling] Did you really mean 'Polkadot'?
docs/nodes/index.mdx|109 col 89| [Vale.Spelling] Did you really mean 'Mainnet'?
docs/nodes/index.mdx|113 col 11| [Vale.Spelling] Did you really mean 'validator'?
docs/nodes/index.mdx|113 col 26| [Vale.Spelling] Did you really mean 'Permissioned'?
docs/nodes/index.mdx|113 col 83| [Vale.Spelling] Did you really mean 'FNOs'?
docs/nodes/index.mdx|113 col 144| [Vale.Spelling] Did you really mean 'SPOs'?
docs/nodes/index.mdx|114 col 22| [Vale.Spelling] Did you really mean 'system_parameters'?
docs/nodes/index.mdx|114 col 68| [Vale.Spelling] Did you really mean 'permissioned'?
docs/nodes/index.mdx|115 col 3| [Vale.Spelling] Did you really mean 'Validator'?
docs/nodes/index.mdx|123 col 42| [Vale.Spelling] Did you really mean 'Mainchain'?
docs/nodes/index.mdx|129 col 12| [Vale.Terms] Use 'Midnight' instead of 'midnight'.
docs/nodes/index.mdx|130 col 12| [Vale.Terms] Use 'Midnight' instead of 'midnight'.
docs/nodes/index.mdx|133 col 88| [Vale.Spelling] Did you really mean 'Mainchain'?
docs/nodes/index.mdx|142 col 57| [Vale.Spelling] Did you really mean 'Schnorrkel'?
docs/nodes/index.mdx|142 col 70| [Vale.Spelling] Did you really mean 'Ristretto'?
docs/nodes/node-endpoints.mdx|135 col 4| [Midnight.HeadingSentenceCase] 'Common RPC queries' should be in sentence case.
docs/nodes/node-endpoints.mdx|155 col 5| [Midnight.HeadingSentenceCase] 'List available RPC methods' should be in sentence case.
docs/nodes/node-endpoints.mdx|251 col 26| [Vale.Spelling] Did you really mean 'validator'?
docs/nodes/rpc-node.mdx|13 col 3| [Midnight.HeadingSentenceCase] 'Set up RPC node for Midnight' should be in sentence case.
docs/nodes/rpc-node.mdx|27 col 4| [Midnight.HeadingSentenceCase] 'Set up an RPC node' should be in sentence case.
docs/nodes/rpc-node.mdx|31 col 5| [Midnight.HeadingSentenceCase] 'Step 1: Configure PostgreSQL database' should be in sentence case.
docs/nodes/rpc-node.mdx|39 col 57| [Vale.Spelling] Did you really mean 'cexplorer'?
docs/nodes/rpc-node.mdx|41 col 5| [Midnight.HeadingSentenceCase] 'Step 2: Run the Docker command for an RPC node' should be in sentence case.
docs/nodes/rpc-node.mdx|110 col 5| [Midnight.HeadingSentenceCase] 'Configure RPC methods' should be in sentence case.
docs/nodes/rpc-node.mdx|123 col 24| [Vale.Spelling] Did you really mean 'nginx'?
docs/nodes/rpc-node.mdx|123 col 31| [Vale.Spelling] Did you really mean 'Caddy'?
docs/nodes/rpc-node.mdx|129 col 4| [Midnight.HeadingSentenceCase] 'Verify the node' should be in sentence case.

Comment thread docs/nodes/boot-node.mdx Outdated
Comment thread docs/nodes/boot-node.mdx Outdated
Comment thread docs/nodes/boot-node.mdx Outdated
Comment thread docs/nodes/boot-node.mdx Outdated
Comment thread docs/nodes/boot-node.mdx Outdated
Comment thread docs/nodes/full-node.mdx Outdated
Comment thread docs/nodes/full-node.mdx Outdated
Comment thread docs/nodes/full-node.mdx Outdated
Comment thread docs/nodes/full-node.mdx Outdated
Comment thread docs/nodes/full-node.mdx Outdated
Copy link
Copy Markdown

@github-actions github-actions bot left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Remaining comments which cannot be posted as a review comment to avoid GitHub Rate Limit

vale

docs/nodes/index.mdx|114 col 22| [Vale.Spelling] Did you really mean 'system_parameters'?
docs/nodes/index.mdx|114 col 68| [Vale.Spelling] Did you really mean 'permissioned'?
docs/nodes/index.mdx|115 col 3| [Vale.Spelling] Did you really mean 'Validator'?
docs/nodes/index.mdx|123 col 42| [Vale.Spelling] Did you really mean 'Mainchain'?
docs/nodes/index.mdx|129 col 12| [Vale.Terms] Use 'Midnight' instead of 'midnight'.
docs/nodes/index.mdx|130 col 12| [Vale.Terms] Use 'Midnight' instead of 'midnight'.
docs/nodes/index.mdx|133 col 88| [Vale.Spelling] Did you really mean 'Mainchain'?
docs/nodes/index.mdx|142 col 57| [Vale.Spelling] Did you really mean 'Schnorrkel'?
docs/nodes/index.mdx|142 col 70| [Vale.Spelling] Did you really mean 'Ristretto'?
docs/nodes/cardano-node.mdx|13 col 3| [Midnight.HeadingSentenceCase] 'Set up Cardano node' should be in sentence case.
docs/nodes/cardano-node.mdx|16 col 223| [Vale.Spelling] Did you really mean 'queryable'?
docs/nodes/cardano-node.mdx|18 col 126| [Vale.Terms] Use 'Cardano' instead of 'cardano'.
docs/nodes/cardano-node.mdx|80 col 4| [Vale.Spelling] Did you really mean 'Mithril'?
docs/nodes/cardano-node.mdx|82 col 18| [Vale.Spelling] Did you really mean 'Mithril'?
docs/nodes/cardano-node.mdx|128 col 5| [Midnight.HeadingSentenceCase] 'Install Mithril tooling' should be in sentence case.
docs/nodes/cardano-node.mdx|128 col 13| [Vale.Spelling] Did you really mean 'Mithril'?
docs/nodes/cardano-node.mdx|136 col 9| [Vale.Spelling] Did you really mean 'Mithril'?
docs/nodes/cardano-node.mdx|144 col 50| [Vale.Spelling] Did you really mean 'Mithril'?
docs/nodes/cardano-node.mdx|147 col 19| [Vale.Spelling] Did you really mean 'Mithril'?
docs/nodes/cardano-node.mdx|196 col 5| [Vale.Spelling] Did you really mean 'Mithril'?
docs/nodes/cardano-node.mdx|196 col 150| [Midnight.Readability] 'be used' should be in the active voice.
docs/nodes/cardano-node.mdx|198 col 4| [Midnight.HeadingSentenceCase] 'Setup Cardano relay node' should be in sentence case.
docs/nodes/cardano-node.mdx|239 col 78| [Vale.Spelling] Did you really mean 'config'?
docs/nodes/cardano-node.mdx|241 col 21| [Vale.Spelling] Did you really mean 'config'?
docs/nodes/cardano-node.mdx|258 col 62| [Midnight.Readability] 'be invoked' should be in the active voice.
docs/nodes/cardano-node.mdx|269 col 5| [Midnight.HeadingSentenceCase] 'Inject Mithril snapshot (optional)' should be in sentence case.
docs/nodes/cardano-node.mdx|269 col 12| [Vale.Spelling] Did you really mean 'Mithril'?
docs/nodes/cardano-node.mdx|283 col 8| [Vale.Spelling] Did you really mean 'thedatabase'?
docs/nodes/cardano-node.mdx|283 col 24| [Midnight.Readability] 'been moved' should be in the active voice.
docs/nodes/cardano-node.mdx|289 col 5| [Midnight.HeadingSentenceCase] 'Run Cardano node' should be in sentence case.
docs/nodes/cardano-node.mdx|291 col 30| [Midnight.Readability] 'be invoked' should be in the active voice.
docs/nodes/cardano-node.mdx|291 col 51| [Vale.Spelling] Did you really mean 'config'?
docs/nodes/cardano-node.mdx|291 col 159| [Vale.Spelling] Did you really mean 'Mithril'?
docs/nodes/cardano-node.mdx|323 col 33| [Vale.Spelling] Did you really mean 'mainnet'?
docs/nodes/cardano-node.mdx|361 col 121| [Vale.Spelling] Did you really mean 'mainnet'?
docs/nodes/cardano-node.mdx|361 col 144| [Vale.Spelling] Did you really mean 'testnets'?
docs/nodes/cardano-node.mdx|438 col 8| [Vale.Spelling] Did you really mean 'systemd'?
docs/nodes/node-endpoints.mdx|137 col 4| [Midnight.HeadingSentenceCase] 'Common RPC queries' should be in sentence case.
docs/nodes/node-endpoints.mdx|157 col 5| [Midnight.HeadingSentenceCase] 'List available RPC methods' should be in sentence case.
docs/nodes/node-endpoints.mdx|253 col 26| [Vale.Spelling] Did you really mean 'validator'?
docs/nodes/rpc-node.mdx|13 col 3| [Midnight.HeadingSentenceCase] 'Set up RPC node for Midnight' should be in sentence case.
docs/nodes/rpc-node.mdx|26 col 4| [Midnight.HeadingSentenceCase] 'Run the Midnight node in RPC mode' should be in sentence case.
docs/nodes/rpc-node.mdx|63 col 5| [Midnight.HeadingSentenceCase] 'Configure RPC methods' should be in sentence case.

Comment thread docs/nodes/boot-node.mdx
Comment thread docs/nodes/cardano-db-sync.mdx
Comment thread docs/nodes/cardano-db-sync.mdx
Comment thread docs/nodes/cardano-db-sync.mdx
Comment thread docs/nodes/cardano-db-sync.mdx
Comment thread docs/nodes/index.mdx Outdated
Comment thread docs/nodes/index.mdx Outdated
Comment thread docs/nodes/index.mdx Outdated
Comment thread docs/nodes/index.mdx Outdated
Comment thread docs/nodes/index.mdx Outdated
Copy link
Copy Markdown

@github-actions github-actions bot left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Remaining comments which cannot be posted as a review comment to avoid GitHub Rate Limit

vale

docs/nodes/rpc-node.mdx|13 col 3| [Midnight.HeadingSentenceCase] 'Set up RPC node for Midnight' should be in sentence case.
docs/nodes/rpc-node.mdx|26 col 4| [Midnight.HeadingSentenceCase] 'Run the Midnight node in RPC mode' should be in sentence case.
docs/nodes/rpc-node.mdx|63 col 5| [Midnight.HeadingSentenceCase] 'Configure RPC methods' should be in sentence case.
docs/nodes/index.mdx|19 col 44| [Vale.Spelling] Did you really mean 'permissioned'?
docs/nodes/index.mdx|19 col 57| [Vale.Spelling] Did you really mean 'FNOs'?
docs/nodes/index.mdx|19 col 104| [Vale.Spelling] Did you really mean 'SPOs'?
docs/nodes/index.mdx|110 col 77| [Vale.Spelling] Did you really mean 'Mainnet'?
docs/nodes/index.mdx|115 col 11| [Vale.Spelling] Did you really mean 'validator'?
docs/nodes/index.mdx|115 col 26| [Vale.Spelling] Did you really mean 'Permissioned'?
docs/nodes/index.mdx|115 col 83| [Vale.Spelling] Did you really mean 'FNOs'?
docs/nodes/index.mdx|115 col 144| [Vale.Spelling] Did you really mean 'SPOs'?
docs/nodes/index.mdx|116 col 70| [Vale.Spelling] Did you really mean 'permissioned'?
docs/nodes/index.mdx|122 col 12| [Vale.Terms] Use 'Midnight' instead of 'midnight'.
docs/nodes/index.mdx|123 col 12| [Vale.Terms] Use 'Midnight' instead of 'midnight'.
docs/nodes/index.mdx|126 col 87| [Vale.Spelling] Did you really mean 'Mainchain'?
docs/nodes/index.mdx|135 col 56| [Vale.Spelling] Did you really mean 'Schnorrkel'?
docs/nodes/index.mdx|135 col 69| [Vale.Spelling] Did you really mean 'Ristretto'?
docs/nodes/node-endpoints.mdx|137 col 4| [Midnight.HeadingSentenceCase] 'Common RPC queries' should be in sentence case.
docs/nodes/node-endpoints.mdx|157 col 5| [Midnight.HeadingSentenceCase] 'List available RPC methods' should be in sentence case.
docs/nodes/node-endpoints.mdx|253 col 26| [Vale.Spelling] Did you really mean 'validator'?

Comment thread docs/nodes/full-node.mdx
Comment thread docs/nodes/full-node.mdx
Comment thread docs/nodes/cardano-node.mdx
Comment thread docs/nodes/cardano-node.mdx
Comment thread docs/nodes/cardano-node.mdx
Comment thread docs/nodes/cardano-node.mdx Outdated
Comment thread docs/nodes/cardano-node.mdx Outdated
Comment thread docs/nodes/cardano-node.mdx Outdated
Comment thread docs/nodes/cardano-node.mdx Outdated
Comment thread docs/nodes/cardano-node.mdx Outdated
Comment thread docs/nodes/index.mdx
Comment thread docs/nodes/index.mdx
Comment thread docs/nodes/index.mdx
Comment thread docs/nodes/index.mdx
Comment thread docs/nodes/index.mdx
Comment thread docs/nodes/node-endpoints.mdx
Comment thread docs/nodes/node-endpoints.mdx
Comment thread docs/nodes/rpc-node.mdx
Comment thread docs/nodes/rpc-node.mdx
Comment thread docs/nodes/rpc-node.mdx
@gyrationtechs gyrationtechs marked this pull request as ready for review March 27, 2026 16:10
@gyrationtechs gyrationtechs changed the title doc: rewrite Nodes section [WIP] doc: rewrite Nodes section Mar 27, 2026
@Emmanuel-Tyty
Copy link
Copy Markdown

Emmanuel-Tyty commented Mar 30, 2026

We should definitely not do away with docker, having both is good. Docker for local setup is super important for newbies especially. Unless I am missing something.

@nstanford5 nstanford5 mentioned this pull request Mar 30, 2026
3 tasks
@DianaHackmamba
Copy link
Copy Markdown
Contributor

@gyrationtechs - LMK when you are ready for my review.


### Run Cardano node

When you start `cardano-node`, provide the configuration file paths from `~/.local/bin/share/<network: preprod, mainnet, preview>` and the database path. The Mithril client has already downloaded a snapshot of the *Cardano Preprod* database to `~/cardano-preprod/db`.
Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

🚫 [vale] reported by reviewdog 🐶
[Vale.Spelling] Did you really mean 'Mithril'?

</TabItem>
</Tabs>

If you took the snapshot of the Mainnet database, then the `node.socket` file is *not* created until the node has completed its internal initialization. The process includes validating the database and replaying any necessary blocks. Therefore, you will need to wait.
Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

🚫 [vale] reported by reviewdog 🐶
[Vale.Spelling] Did you really mean 'Mainnet'?

When you run `cardano-cli query tip`, you are asking your local node for its "current view" of the blockchain. Since your node is still syncing, this output represents where your node is currently positioned compared to the total history of the network.

- **`"block"`**: This is the height of the last block your node has processed. In this case, it has reached block *136,111*.
- **`"epoch"`**: The current epoch your node is looking at. An epoch is a specific time period, equivalent to 5 days on Mainnet, but varies on testnets. The node is currently in *Epoch 10*.
Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

🚫 [vale] reported by reviewdog 🐶
[Vale.Spelling] Did you really mean 'Mainnet'?

Comment thread docs/nodes/cardano-node.mdx
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.

3 participants