docs/node/run-your-node: Add compatibility matrix for archive nodes #1599
Conversation
✅ Deploy Preview for oasisprotocol-docs ready!
To edit notification comments on pull requests, go to your Netlify project configuration. |
peternose
left a comment
peternose
left a comment
There was a problem hiding this comment.
Nice, very good summary, which probably took a lot of time. I did not check if the matrix is correct and everything works :)
I posted few comments about how I would organize the guide.
|
|
||
| # Archive Node | ||
|
|
||
| This guide will cover setting up an archive node for the Oasis Network. Node |
There was a problem hiding this comment.
| This guide will cover setting up an archive node for the Oasis Network. Node | |
| This guide covers setting up an archive node for the Oasis Network. | |
| An archive node serves historical consensus and runtime state that cannot normally be accessed through other nodes in the network because the state has been pruned or removed during dump-and-restore network upgrades. The node does not actively participate in the consensus protocol and has most of the node features disabled. |
Let split intro and archive node description.
I would somewhere also mention that the node doesn't need to be registered neither added to an existing entity, but not sure where.
| it will not participate in the network. Archive nodes can be used to access | ||
| historic state which is pruned in dump-restore network upgrades. | ||
|
|
||
| ## Prerequisites |
There was a problem hiding this comment.
Too general, should be avoided. Maybe change to historical state and define below what snapshot is and where can it be accessed.
|
|
||
| ## Prerequisites | ||
|
|
||
| Running an archive node requires a pre-existing `oasis-node` state. If you don't have one, |
There was a problem hiding this comment.
Term oasis-node state is confusing. Let's stick with historical consensus and runtime state.
| ## Prerequisites | ||
|
|
||
| Running an archive node requires a pre-existing `oasis-node` state. If you don't have one, | ||
| you can download a snapshot of a specific network state [here][snapshots]. |
There was a problem hiding this comment.
Instead of here you should use a proper name, e.g. on our official Snapshot page or something better.
Maybe also define what snapshot is, how to extract it and when new snapshots are added.
|
|
||
| [snapshots]: https://snapshots.oasis.io | ||
|
|
||
| ## Configuration (Oasis Core 23 and later) |
There was a problem hiding this comment.
The title is too long and intro text is missing. It should be changed to something like:
## Configuration (use better name)
Archive nodes can be configured with different historical state, ....
- Oasis Core 22 and earlier
- ...
### Oasis Core 23 and latter
### Oasis Core 22 and earlier
| Starting from the Oasis Core version 23, the configuration for enabling archive mode has changed. | ||
| Use the `mode` setting: | ||
|
|
||
| :::info |
There was a problem hiding this comment.
I would avoid this, as they completely destroy reading flow. Keep it simple.
|
|
||
| #### Damask | ||
|
|
||
| To run an archive node for Damask, use [Oasis Core v22.2.13] and the following |
There was a problem hiding this comment.
How do I know which snapshot to use?
|
|
||
| ::: | ||
|
|
||
| ## Starting the Oasis Node |
There was a problem hiding this comment.
| ## Starting the Oasis Node | |
| ## Starting |
People might confuse archive and oasis node. Let's have simple sections, e.g. configuration/setup, deployment, ... or configuring archive node, starting/running archive node.
It would be nice to have again intro text for these sections so that people know what is coming, e.g. something like this, but better;
To run your own archive node for a specific historical state you need to:
- Download snapshot
- Configure archive node
- Start archive node
- ...
### Download snapshot
### Configure archive node
### Start archive node
| oasis-node --config /node/etc/config.yml | ||
| ``` | ||
|
|
||
| ### Archive node status |
There was a problem hiding this comment.
This title can be removed.
| } | ||
| ``` | ||
|
|
||
| ## Version Compatibility Matrix |
There was a problem hiding this comment.
When I read the title I have no idea what this is. So it would be better to rename it to snapshots or historical state, move it higher (because this will be the first thing a user needs to do), describe what snapshot is, and then transition to this compatibility matrix.
There was a problem hiding this comment.
I guess the right order of the guide should be the same as how a user would deploy this:
- Select which historical state you want to serve with archive node
- Download correct snapshot and binary
- Prepare configuration
- Run the node
|
Maybe we should also move seed node and archive node guide lower, as are less important. I would expect the following order: validator, non-validator, compute, client, key manager, archive, seed, sentry. |
Documenting compatible versions for setting up Oasis archive nodes for previous network generations.