From 591a9f352c7da1e1665a3b4ec188e4d758d669cb Mon Sep 17 00:00:00 2001 From: Alexander Kolesov Date: Sun, 25 Jul 2021 15:23:13 +0300 Subject: [PATCH 1/3] Improve the instruction on how to join existing network --- docs/how-to-join-existing-network.md | 45 +++++++++++++ ...twork.md => how-to-setup-a-new-network.md} | 64 ++++++------------- ...alidator.md => how-to-setup-a-new-node.md} | 56 ++++++++-------- 3 files changed, 90 insertions(+), 75 deletions(-) create mode 100644 docs/how-to-join-existing-network.md rename docs/{how-to-deploy-genesis-network.md => how-to-setup-a-new-network.md} (60%) rename docs/{how-to-setup-a-new-validator.md => how-to-setup-a-new-node.md} (66%) diff --git a/docs/how-to-join-existing-network.md b/docs/how-to-join-existing-network.md new file mode 100644 index 000000000..2d4e650a3 --- /dev/null +++ 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 ` + + 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 ` + +3. Promote the node to the validator: + + - **Post `create-validator` transaction to the network:** + + ``` + cheqd-noded tx staking create-validator --amount --from --chain-id --min-self-delegation --gas --gas-prices --pubkey --commission-max-change-rate --commission-max-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 ``: `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 b/docs/how-to-setup-a-new-network.md similarity index 60% rename from docs/how-to-deploy-genesis-network.md rename to docs/how-to-setup-a-new-network.md index 868e83341..ae414f87a 100644 --- a/docs/how-to-deploy-genesis-network.md +++ b/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 for the network. +1. Participants must choose `` 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 --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: `d45dcc54583d6223ba6d4b3876928767681e8ff6@192.168.0.142: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: `@, @, @, @`. @@ -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 b/docs/how-to-setup-a-new-node.md similarity index 66% rename from docs/how-to-setup-a-new-validator.md rename to docs/how-to-setup-a-new-node.md index 02f96f021..1edacdc4e 100644 --- a/docs/how-to-setup-a-new-validator.md +++ b/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,7 +27,7 @@ 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). @@ -113,40 +115,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 - -Follow these steps to promote the deployed node to a validator: - -1. Create an account: +## Getting node info - - **Generate local keys for the future account:** +### Node id - Command: `cheqd-noded keys add ` +Node id is a part of peer info. To get `node id` run the following command on the node's machine: - Example: `cheqd-noded keys add alice` +``` +cheqd-noded tendermint show-node-id +``` - - **Ask another member to transfer some tokens:** +### Validator public key - Tokens are used to post transactions. It also used to create a stake for new nodes. +Validator public key is used to promote node to the validator. To get it run the following command on the node's machine: - Another mmber will ask for the address of the new participant. Cosmos account address is a function of the public key. +``` +cheqd-noded tendermint show-validator +``` - Use this command to find out your adress and other key information: `cheqd-noded keys show ` +### Peer information -3. Promote the node to the validator: +Peer info is used to connect to peers when setting up a new node. It has the following format: - - **Post a transaction to the network:** - - ``` - cheqd-noded tx staking create-validator --amount --from --chain-id --min-self-delegation --gas --gas-prices --pubkey --commission-max-change-rate --commission-max-rate --commission-rate - ``` +``` +@ +``` - `commission-max-change-rate`, `commission-max-rate` and `commission-rate` may take fraction number as `0.01` +Example: - Use this command to find out the ``: `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" - ``` +``` +ba1689516f45be7f79c7450394144711e02e7341@3.13.19.41:26656 +``` From f362885d83d0ac7e8faf4f290ed03df9e8254b92 Mon Sep 17 00:00:00 2001 From: Andrew Nikitin Date: Fri, 30 Jul 2021 14:14:13 +0300 Subject: [PATCH 2/3] Add lines about .deb package Signed-off-by: Andrew Nikitin --- docs/deb-package-installation.md | 90 ++++++++++++++++++++++++++++++++ 1 file changed, 90 insertions(+) create mode 100644 docs/deb-package-installation.md diff --git a/docs/deb-package-installation.md b/docs/deb-package-installation.md new file mode 100644 index 000000000..9bfe440ec --- /dev/null +++ b/docs/deb-package-installation.md @@ -0,0 +1,90 @@ +## Overview +One of the possible distribution way is to use debian package. +It's the most common way for Ubuntu OS and also it can provide post-install steps which can help to make our application as a service. +Because we have to run init procedure for creating tree of directories, `configs` and `data`, not all the steps can be automated. +By the way, debian package consists of binary, named `cheqd-noded` and script with post-install and post-remove actions. + +## Post-install actions +### Create a special user "cheqd" +By default, cosmos-sdk create all needed directories in the `HOME` directory. +That's why package creates a special user with home directory `/home/cheqd`. Also, this user will use for setting permissions to data and configs. + +### Dividing configs, data and logs +#### Directories +According to general filesystem hierarchy standard (FHS), the next directories will be created: +``` +/etc/cheqd-node - configs, permissions cheqd:cheqd +/var/lib/cheqd-node/ - data , permissions cheqd:cheqd +/var/log/cheqd-node - logs , permissions syslog:adm (set by rsyslog) +``` +#### Rsyslog config +The next config for rsyslog will be created: +``` +if \$programname == 'cheqd-noded' then /var/log/cheqd-node/stdout.log +& stop +``` +It redirects all the logs into the file. +#### Logrotate config +For rotating log file will be used `logrotate` - the general approach for Linux/systemd with the next config: +``` +/var/log/cheqd-node/stdout.log { + rotate 30 + maxsize 100M + notifempty + copytruncate + compress + maxage 30 +} +``` +It means, that log will be rotated after achieving 100 Mb size of `stdout.log` and compressed. +All the archives will be stored for a month (30 days). Also, the main file will truncated instead of removing. It needs for continue logging process in terms of file pointers. + +Once a day by crontab will be called a small script for running logrotate logic. + +### Systemd +The main part of post-installation process is making our binary as a service. Systemd service file can help with it: +``` +[Unit] +Description=Service for running Cheqd node +After=network.target +[Service] +Type=simple +User=cheqd +ExecStart=/bin/bash -c '/usr/bin/cheqd-noded start' +Restart=on-failure +RestartSec=10 +StartLimitBurst=10 +StartLimitInterval=200 +TimeoutSec=300 +StandardOutput=syslog +StandardError=syslog +SyslogFacility=syslog +SyslogIdentifier=cheqd-noded +[Install] +WantedBy=multi-user.target +``` +The main thing here is that it will restart on binary failures and put all output to the `rsyslog`. + +## Actions that can be deployed manually +After setting up the node, it's expected, then configs and data will be symlinked to the corresponded system directories. +Please, make sure that service was stopped, by checking output: +``` +systemctl status cheqd-noded.service +``` +Commands can be: +``` +sudo ln -s /etc/cheqd-node/config /home/cheqd/.cheqdnode/config - for configs +sudo ln -s /var/lib/cheqd-node/data/ /home/cheqd/.cheqdnode/ - for data +``` + +## Exposing port + + +## Post-remove actions +For now, all files created during installation process will be removed from the system, like: +``` +/etc/rsyslog.d/cheqd-node.conf +/etc/logrotate.d/cheqd-node +/etc/cron.daily/cheqd-node +/etc/systemd/system/cheqd-noded.service +``` From 9cce648672ca2b12989cb6d0b4c6bafe564b845a Mon Sep 17 00:00:00 2001 From: Andrew Nikitin Date: Fri, 30 Jul 2021 19:58:21 +0300 Subject: [PATCH 3/3] Add lines about .deb package Signed-off-by: Andrew Nikitin --- docs/deb-package-instalation.md | 90 --------------------------------- docs/how-to-setup-a-new-node.md | 13 +++-- 2 files changed, 6 insertions(+), 97 deletions(-) delete mode 100644 docs/deb-package-instalation.md diff --git a/docs/deb-package-instalation.md b/docs/deb-package-instalation.md deleted file mode 100644 index 9bfe440ec..000000000 --- a/docs/deb-package-instalation.md +++ /dev/null @@ -1,90 +0,0 @@ -## Overview -One of the possible distribution way is to use debian package. -It's the most common way for Ubuntu OS and also it can provide post-install steps which can help to make our application as a service. -Because we have to run init procedure for creating tree of directories, `configs` and `data`, not all the steps can be automated. -By the way, debian package consists of binary, named `cheqd-noded` and script with post-install and post-remove actions. - -## Post-install actions -### Create a special user "cheqd" -By default, cosmos-sdk create all needed directories in the `HOME` directory. -That's why package creates a special user with home directory `/home/cheqd`. Also, this user will use for setting permissions to data and configs. - -### Dividing configs, data and logs -#### Directories -According to general filesystem hierarchy standard (FHS), the next directories will be created: -``` -/etc/cheqd-node - configs, permissions cheqd:cheqd -/var/lib/cheqd-node/ - data , permissions cheqd:cheqd -/var/log/cheqd-node - logs , permissions syslog:adm (set by rsyslog) -``` -#### Rsyslog config -The next config for rsyslog will be created: -``` -if \$programname == 'cheqd-noded' then /var/log/cheqd-node/stdout.log -& stop -``` -It redirects all the logs into the file. -#### Logrotate config -For rotating log file will be used `logrotate` - the general approach for Linux/systemd with the next config: -``` -/var/log/cheqd-node/stdout.log { - rotate 30 - maxsize 100M - notifempty - copytruncate - compress - maxage 30 -} -``` -It means, that log will be rotated after achieving 100 Mb size of `stdout.log` and compressed. -All the archives will be stored for a month (30 days). Also, the main file will truncated instead of removing. It needs for continue logging process in terms of file pointers. - -Once a day by crontab will be called a small script for running logrotate logic. - -### Systemd -The main part of post-installation process is making our binary as a service. Systemd service file can help with it: -``` -[Unit] -Description=Service for running Cheqd node -After=network.target -[Service] -Type=simple -User=cheqd -ExecStart=/bin/bash -c '/usr/bin/cheqd-noded start' -Restart=on-failure -RestartSec=10 -StartLimitBurst=10 -StartLimitInterval=200 -TimeoutSec=300 -StandardOutput=syslog -StandardError=syslog -SyslogFacility=syslog -SyslogIdentifier=cheqd-noded -[Install] -WantedBy=multi-user.target -``` -The main thing here is that it will restart on binary failures and put all output to the `rsyslog`. - -## Actions that can be deployed manually -After setting up the node, it's expected, then configs and data will be symlinked to the corresponded system directories. -Please, make sure that service was stopped, by checking output: -``` -systemctl status cheqd-noded.service -``` -Commands can be: -``` -sudo ln -s /etc/cheqd-node/config /home/cheqd/.cheqdnode/config - for configs -sudo ln -s /var/lib/cheqd-node/data/ /home/cheqd/.cheqdnode/ - for data -``` - -## Exposing port - - -## Post-remove actions -For now, all files created during installation process will be removed from the system, like: -``` -/etc/rsyslog.d/cheqd-node.conf -/etc/logrotate.d/cheqd-node -/etc/cron.daily/cheqd-node -/etc/systemd/system/cheqd-noded.service -``` diff --git a/docs/how-to-setup-a-new-node.md b/docs/how-to-setup-a-new-node.md index 1edacdc4e..b2e0c0938 100644 --- a/docs/how-to-setup-a-new-node.md +++ b/docs/how-to-setup-a-new-node.md @@ -31,6 +31,7 @@ There are several ways to get binary: - 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: @@ -39,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: @@ -98,10 +97,10 @@ Follow these steps to deploy a new node: Allow all outgoing tcp connections for P2P communication. You can restrict port to the default P2P port `26656` but your node will not be able to connect to nodes with non default P2P port in this case. 8. Start node: - - Command: `cheqd-noded start` - - It's highly recommended to use a process supervisor like `systemd` to run persistent nodes. + + 8.1 In case of using tarball: `cheqd-noded start` + + 8.2 In case of using `.deb` package:`systemctl start cheqd-noded.service` 9. (optional) Setup sentry nodes for DDOS protection: