Merge pull request #89 from cheqd/featre/doc-improvements

Improve the instruction on how to join existing network
cheqd · Aug 3, 2021 · 45cf5ab · 45cf5ab
2 parents 2fde44c + 764a007
commit 45cf5ab
Show file tree

Hide file tree

Showing 4 changed files with 95 additions and 81 deletions.
diff --git a/docs/deb-package-instalation.md → docs/deb-package-installation.md b/docs/deb-package-instalation.md → docs/deb-package-installation.md
diff --git a/docs/how-to-join-existing-network.md b/docs/how-to-join-existing-network.md
@@ -0,0 +1,45 @@
+# Running a new Validator Node
+
+This document describes in detail how to join existing network as validator.
+
+## Steps
+
+1. Setup a node:
+
+    Follow [this instruction](how-to-setup-a-new-node.md).
+
+    Use corresponding `genesis.json` and `persistent peers list` form `persistent_chains` folder in the root of the repository.
+
+2. Create an account:
+
+    - **Generate local keys for the future account:**
+
+        Command: `cheqd-noded keys add <key_name>`
+
+        Example: `cheqd-noded keys add alice`
+
+    - **Ask another member to transfer some tokens:**
+
+        Tokens are used to post transactions. It also used to create a stake for new nodes.
+
+        Another mmber will ask for the address of the new participant. Cosmos account address is a function of the public key.
+
+        Use this command to find out your adress and other key information: `cheqd-noded keys show <key_name>`
+
+3. Promote the node to the validator:
+
+    - **Post `create-validator` transaction to the network:**
+
+        ```
+        cheqd-noded tx staking create-validator --amount <amount-staking> --from <key-name> --chain-id <chain-id> --min-self-delegation <min-self-delegation> --gas <amount-gas> --gas-prices <price-gas> --pubkey <validator-pubkey> --commission-max-change-rate <commission-max-change-rate> --commission-max-rate <commission-max-rate> --commission-rate <commission-rate>
+        ```
+
+        `commission-max-change-rate`, `commission-max-rate` and `commission-rate` may take fraction number as `0.01`
+
+        Use this command to find out the `<validator-pubkey>`: `cheqd-noded tendermint show-validator`. This command **MUST** be run on the node's machine.
+        
+        Example:
+        
+        ```
+        cheqd-noded tx staking create-validator --amount 50000000stake --from steward1 --moniker steward1 --chain-id cheqdnode --min-self-delegation="1" --gas="auto" --gas-prices="1token" --pubkey cosmosvalconspub1zcjduepqpmyzmytdzjhf2fjwttjsrv49t62gdexm2yttpmgzh38p0rncqg8ssrxm2l --commission-max-change-rate="0.02" --commission-max-rate="0.02" --commission-rate="0.01"
+        ```
diff --git a/docs/how-to-deploy-genesis-network.md → docs/how-to-setup-a-new-network.md b/docs/how-to-deploy-genesis-network.md → docs/how-to-setup-a-new-network.md
@@ -20,9 +20,13 @@ Current delivery is compiled and tested for `Ubuntu 20.04 LTS` so we recommend u
 
 ## Deployment steps
 
+### Setting up nodes
+
+All participants should [setup their nodes](how-to-setup-a-new-node.md) using default genesis and empty list of peers.
+
 ### Generating genesis file
 
-1. Participants must choose <chain_id> for the network.
+1. Participants must choose `<chain_id>` for the network.
 2. Each participant (one by one) should:
 
     - **Generate local keys for the future account:**
@@ -31,12 +35,6 @@ Current delivery is compiled and tested for `Ubuntu 20.04 LTS` so we recommend u
 
         Example `cheqd-noded keys add alice`
 
-    - **Initialize node config files:**
-
-        Command: `cheqd-noded init <node_name> --chain-id <chain_id>`
-
-        Example: `cheqd-noded init alice-node --chain-id cheqd-node`
-
     - **(Each participant except the first one) Get genesis config from the another participant:**
 
         Location on the previous participant's machine: `$HOME/.cheqdnode/config/genesis.json`
@@ -76,36 +74,26 @@ Current delivery is compiled and tested for `Ubuntu 20.04 LTS` so we recommend u
     - **Share genesis with other nodes:**
 
         Location on the last participant's machine: `$HOME/.cheqdnode/config/genesis.json`
-
-        Destination folder on the other participant's machines: `$HOME/.cheqdnode/config/`
 
-### After these steps
-- Nodes of all participants have the same genesis;
-- The genesis contains:
-    - Accounts of all participants (genesis accounts);
-    - Node creation transactions from all participants (genesis nodes).
+### Sharing peer list
 
-### Running the network
+All participants should share their peer info with each other. See [node setup instruction](how-to-setup-a-new-node.md) for more information.
 
-- Each participant:
+### Updating genesis and persistent peers
 
-    - **Shares their node ID and IP with the others:**
-
-        Command to find out node's id: `cheqd-noded tendermint show-node-id`. This command **MUST** be run on the machine where node's config files are located.
-
-        Node IP is external IP of the node's machine.
-
-        Node adress is the combination of IP and ID in the following format: `ID@IP`.
-
-        Port is the RPC adress of the node. It can be configured here: `$HOME/.cheqdnode/config/config.toml`. Default value is `26656`.
-
-        Node address example: `[email protected]:26656`
-
-    - **Update the address book of the node:**
+- Each participant should:
+
+    - **Stop the node;**
+
+    - **Update the genesis file:**
+
+        File location: `$HOME/.cheqdnode/config/genesis.json`
+
+    - **Update peer list:**
 
         Open node's config file: `$HOME/.cheqdnode/config/config.toml`
 
-        Search for `persistent_peers` parameter and set it's value to a comma separated list of other participant node addresses.
+        Search for `persistent_peers` parameter and set it's value to a comma separated list of peers.
 
         Format: `<node-0-id>@<node-0-ip>, <node-1-id>@<node-1-ip>, <node-2-id>@<node-2-id>, <node-3-id>@<node-3-id>`.
 
@@ -117,22 +105,8 @@ Current delivery is compiled and tested for `Ubuntu 20.04 LTS` so we recommend u
         persistent_peers = "d45dcc54583d6223ba6d4b3876928767681e8ff6@node0:26656, 9fb6636188ad9e40a9caf86b88ffddbb1b6b04ce@node1:26656, abbcb709fb556ce63e2f8d59a76c5023d7b28b86@node2:26656, cda0d4dbe3c29edcfcaf4668ff17ddcb96730aec@node3:26656"
         ```
         
-    - **Makes RPC endpoint available externally (optional):**
-        
-        This step is necessary if you want to allow incoming client applications connections to your node. Otherwise, the node will be accessible only locally. 
-        
-        Open node configuration file using the text editor that you prefer: `$HOME/.cheqdnode/config/config.toml`
+    - **Restart node.**
         
-        Search for `ladr` parameter in `RPC Server Configuration Options` section and replace it's value to `0.0.0.0:26657`
-                
-        Example: `laddr = "tcp://0.0.0.0:26657"`
-        
-    - **Start node:**
-        
-        Command: `cheqd-noded start`
-        
-        It is recommended to use a process supervisor like `systemd` to run persistent node services.
-
 
 Congratulations, you should have node(s) deployed and running on a network if the above steps succeed.
 

diff --git a/docs/how-to-setup-a-new-validator.md → docs/how-to-setup-a-new-node.md b/docs/how-to-setup-a-new-validator.md → docs/how-to-setup-a-new-node.md
@@ -1,8 +1,10 @@
-# Running a new Validator Node
+# Running a new node
 
-This document describes in detail how to configure a validator node, and add it to the existing network.
+This document describes in detail how to configure infrastructure and deploy a new node (observer or validator).
 
-If a new network needs to be initialized, please first follow the instructions for [creating a new network from genesis](how-to-deploy-genesis-network.md). After this, more validator nodes can be added by following the instructions from this document.
+If a new network needs to be initialized, please first follow the instructions for [creating a new network from genesis](how-to-setup-a-new-network.md).
+
+If a new validator needs to be added to the existing network, please refer to [joining existing network](how-to-join-existing-network.md) instruction.
 
 ### Hardware requirements
 
@@ -25,10 +27,11 @@ Current delivery is compiled and tested for `Ubuntu 20.04 LTS` so we recommend u
 There are several ways to get binary:
 
 - Compile from source code - [instruction](../README.md);
-- Get `tar` archive with the binary compiled for Ubuntu 20.04 in [releases](https://github.com/cheqd/cheqd-node/releases); <-- Recommended
+- Get `tar` archive with the binary compiled for Ubuntu 20.04 in [releases](https://github.com/cheqd/cheqd-node/releases);
 - Get `deb` for Ubuntu 20.04 in [releases](https://github.com/cheqd/cheqd-node/releases);
 - Get docker image form [packages](https://github.com/cheqd/cheqd-node/pkgs/container/cheqd-node).
 
+The most preferable way to get `cheqd-node` is to use `.deb` package. Detailed information about it can be found [here](#deb-package-installation.md)  
 ## Node deployment
 
 Follow these steps to deploy a new node:
@@ -37,9 +40,7 @@ Follow these steps to deploy a new node:
 
     More about hardware requirements can be found [here](https://docs.tendermint.com/master/nodes/running-in-production.html#hardware).
 
-2. Get the binary using one of the [described ways](#binary-distribution);
-
-    It's recommended to put the binary to the location which is in PATH.
+2. In the case of using tarball, put the binary to the location which is in PATH.
 
     Example:
 
@@ -104,11 +105,11 @@ Follow these steps to deploy a new node:
 
 8. Start node:
 
-    Command: `cheqd-noded start`
+    8.1 In case of using tarball: `cheqd-noded start`
 
     It's highly recommended to use a process supervisor like `systemd` to run persistent nodes.
-   
-    **FYI**, in case of installing cheqd-node as a `.deb` package, please log in as a `cheqd` user, by calling `sudo su cheqd`.
+
+    8.2 In case of using `.deb` package:`systemctl start cheqd-noded.service`
 
 9. (optional) Setup sentry nodes for DDOS protection:
 
@@ -122,40 +123,34 @@ Follow these steps to deploy a new node:
 
     You can read advices [here](https://docs.tendermint.com/master/nodes/running-in-production.html).
 
-## Network configuration
+## Getting node info
 
-Follow these steps to promote the deployed node to a validator:
+### Node id
 
-1. Create an account:
+Node id is a part of peer info. To get `node id` run the following command on the node's machine:
 
-    - **Generate local keys for the future account:**
+```
+cheqd-noded tendermint show-node-id
+```
 
-        Command: `cheqd-noded keys add <key_name>`
+### Validator public key
 
-        Example: `cheqd-noded keys add alice`
+Validator public key is used to promote node to the validator. To get it run the following command on the node's machine:
 
-    - **Ask another member to transfer some tokens:**
+```
+cheqd-noded tendermint show-validator
+```
 
-        Tokens are used to post transactions. It also used to create a stake for new nodes.
+### Peer information
 
-        Another mmber will ask for the address of the new participant. Cosmos account address is a function of the public key.
+Peer info is used to connect to peers when setting up a new node. It has the following format:
 
-        Use this command to find out your adress and other key information: `cheqd-noded keys show <key_name>`
+```
+<node-id>@<node-url>
+```
 
-3. Promote the node to the validator:
+Example:
 
-    - **Post a transaction to the network:**
-    
-        ```
-        cheqd-noded tx staking create-validator --amount <amount-staking> --from <key-name> --chain-id <chain-id> --min-self-delegation <min-self-delegation> --gas <amount-gas> --gas-prices <price-gas> --pubkey <validator-pubkey> --commission-max-change-rate <commission-max-change-rate> --commission-max-rate <commission-max-rate> --commission-rate <commission-rate>
-        ```
-
-        `commission-max-change-rate`, `commission-max-rate` and `commission-rate` may take fraction number as `0.01`
-
-        Use this command to find out the `<validator-pubkey>`: `cheqd-noded tendermint show-validator`. This command **MUST** be run on the node's machine.
-        
-        Example:
-        
-        ```
-        cheqd-noded tx staking create-validator --amount 50000000stake --from steward1 --moniker steward1 --chain-id cheqdnode --min-self-delegation="1" --gas="auto" --gas-prices="1token" --pubkey cosmosvalconspub1zcjduepqpmyzmytdzjhf2fjwttjsrv49t62gdexm2yttpmgzh38p0rncqg8ssrxm2l --commission-max-change-rate="0.02" --commission-max-rate="0.02" --commission-rate="0.01"
-        ```
+```
+[email protected]:26656
+```