Setup a new cheqd node
Last updated
Was this helpful?
Last updated
Was this helpful?
This document describes how to use install and configure a new instance of cheqd-node using an interactive installer which supports the following functionality:
Setup a new observer/validator node from scratch
Configure a node to work with the testnet/mainnet network
Upgrade an existing node installation
Alternatively, if you want to manage network upgrades manually, you can also opt for a standadalone installation.
⚠️ Read our guidance on before you get started!
This document specifies the CPU/RAM requirements, firewall ports, and operating system requirements for running cheqd-node.
The interactive installer is written in Python 3 and is designed to work on Ubuntu Linux 20.04 LTS systems. The script has been written to work pre-installed Python 3.x libraries generally available on Ubuntu 20.04.
Cosmovisor (default, but can be skipped): The installer by default, which is a standard Cosmos SDK tool that makes network upgrades happen in an automated fashion. This makes the process of upgrading to new releases for network-wide upgrades easier.
cheqd-noded binary (mandatory): This is the main piece of ledger-side code each node runs.
Dependencies: In case you request the installer to restore from a snapshot, dependencies such as pv will be installed so that a progress bar can be shown for snapshot extraction. Otherwise, no additional software is installed by the installer.
Github.com: Fetch latest releases, configuration files, and network settings.
Cloudflare DNS (optional): Used to fetch an externally-resolvable IP address, if this option is selected during install.
⚠️ The guidance below is intended for straightforward new installations or upgrades.
By default, the installer will attempt to create a backup of the ~/.cheqdnode/config/ directory and important files under ~/.cheqdnode/data/ before making any destructive changes. These backups are created under the cheqd user's home directory in a folder called backup (default location: /home/cheqd/backup). However, for safety, you're recommended to also make manual backups when upgrading a node.
If you're setting up a new node from scratch, you can safely ignore the advice above.
Stop the running services related to your node. If running via Cosmovisor:
Or if running standalone:
To get started, download the interactive installer script:
Then, start the interactive installer:
ℹ️ NOTE: You need to execute this as root or at least a user with super-user privileges using the
sudoprefix to the command.
The interactive installer guides you through setting up and configuring a node installation by asking as series of questions.
All the questions specify the default answer/value for that question in square ([]) brackets, for example, [default: 1]. If a default value exists, you can just press Enter without needing to type the whole answer.
Binary release version to install, automatically fetched from Github. The first release displayed in the list will always be the latest stable version. Other versions displayed below it are pre-release/beta versions.
By default, a new user/group called cheqd will be created and a home directory created for it. The default location is /home/cheqd and any configuration data directories being created under this path at /home/cheqd/.cheqdnode.
Install cheqd-noded using Cosmovisor? (yes/no) [default: yes]: Use Cosmovisor to run node
You can also choose no to installing with Cosmovisor on the first question, in which case a standalone binary installation is carried out.
The next set of questions sets common node configuration parameters. These are the minimal configuration parameters necessary for a node to function, but advanced users can later customise other settings.
What is the externally-reachable IP address or DNS name for your cheqd-node? [default: Fetch automatically via DNS resolver lookup]:: External address is the publicly accessible IP address or DNS name of your cheqd-node. This is used to advertise your node's P2P address to other nodes in the network. If you are running your node behind a NAT, you should set this to your public IP address or DNS name. If you are running your node on a public IP address, you can leave this blank to automatically fetch your IP address via DNS resolver lookup. (Automatic fetching sends a dig request to whoami.cloudflare.com)
Specify persistent peers [default: none]: Persistent peers are nodes that you want to always keep connected to. Values for persistent peers should be specified in format: <nodeID>@<IP>:<port>,<nodeID>@<IP>:<port>.
Specify log level (trace|debug|info|warn|error|fatal|panic) [default: error]:: The default log level of error is generally recommended for normal operation. You may temporarily need to change to more verbose logging levels if trying to diagnose issues if the node isn't behaving correctly.
Specify log format (json|plain) [default: json]:: JSON log format allows parsing log files more easily if there's an issue with your node, hence it's set as the default.
When setting up a new node, you typically need to download all past blocks on the network, including any upgrades that were done along the way with the specific binary releases those upgrades went through.
If you skip this step, you'll need to manually synchronise with the network.
⚠️ Chain snapshots can range from 10 GBs (for testnet) to 100 GBs (for mainnet). Therefore, this step can take a long time.
If you're running the installer on a machine where an existing installation is already present, you'll be prompted whether you want to update/upgrade the existing installation:
If you choose no, this will treat the installation as if installing from scratch and prompt with the questions in section above.
If you choose yes, this will retain existing node configuration and prompt with a different set of questions as outlined below. Choosing "yes" is the default since in most cases, you would want to retain the existing configuration while updating the node binary to a newer version.
If Cosmovisor is detected as installed, you'll be offered the option to bump it to the latest default version. Otherwise, you will be given the option of installing it.
The next section allows you to customise Cosmovisor settings. The explanations of the options are same those given above.
By default, the installer will update the systemd system service settings for the following:
cheqd-cosmovisor.service (if installed with Cosmovisor) or cheqd-noded.service (if installed without Cosmovisor): This is the service that runs the node in the background 24/7.
rsyslog.service: Configures node-specific logging directories and settings.
logrotate.service and logrotate.timer: Configures log rotation for node service to limit the duration/size of logs retained to sensible values. By default, this keeps 7 days worth of logs, and compresses logs if they grow larger than 100 MB in size.
Once all prompts have been answered, the installer attempts to carry out the changes requested. This includes:
Setting up a new cheqd user/group.
Downloading cheqd-noded and Cosmovisor binaries, as applicable.
Setting environment variables required for node binary / Cosmovisor to function.
Creating directories for node data and configuration.
If present, backing up existing node directories and configuration.
Downloading and extracting snapshots (if requested).
⚠️ The guidance below is intended for straightforward new installations or upgrades.
If the installer finishes successfully, it will exit with a success message:
Otherwise, if the installation failed, it will exit with an error message which elaborates on the specific error encountered during setup.
The following steps are only recommended if installation has been successful.
Check that the node-related systemd service is enabled. This ensures that the node service automatically restarted, even if the service fails or if the machine is rebooted.
If installed with Cosmovisor:
The output line after the systemctl status cheqd-cosmovisor.service command should say enabled after Loaded path and vendor preset.
If installed without Cosmovisor (standalone binary install):
The output line after the systemctl status cheqd-noded.service command should say enabled after Loaded path and vendor preset.
Once the node is installed/upgraded, restart the systemd service to get the node running. These steps require root or super-user privileges as a pre-requisite.
If installed with Cosmovisor:
If installed without Cosmovisor:
The command above should start the node service. Ideally, the node service should start running and remain running. You can check this by running the command below a couple of times in succession and checking that the output line remains as Active: running rather than any other status.
(Previous commands can be recalled in bash by pressing the up arrow key on your keyboard to repeat or cycle through previous commands.)
If installed with Cosmovisor:
The output line after the systemctl status cheqd-cosmovisor.service command should say enabled after Loaded path and vendor preset.
If installed without Cosmovisor (standalone binary install):
Once the systemd service is confirmed as running, check that the node is catching up on new blocks by repeating this command 3-5 times:
(Previous commands can be recalled in bash by pressing the up arrow key on your keyboard to repeat or cycle through previous commands.)
Note: The cheqd-noded status may not return a successful response immediately after starting the systemd service. For instance, you might get the following output:
If you encounter the output above, as long as systemctl status ... returns Active, this "error" above is completely normal. This is because it takes a few minutes after systemctl start for the node services to properly start running. Please wait for a few minutes, and then re-run the cheqd-noded status command.
The output might say catching_up: true if the node is still catching up, or catching_up: false if it's fully caught up.
If the node is catching up, the time needed to fully catch up will depend on how far behind your node is. The latest_block_height value in the output shown above will indicate how far behind the node is. This number should display a larger value every time you re-run the command.
Network snapshot server (optional): If requested by the user, the script will fetch latest network snapshots published on and then download snapshot files from the snapshot CDN endpoint ()
If your scenario is more complex, such as in case of or , please review the guidance under .
Join either the existing (chain ID: cheqd-mainnet-1) or (chain ID: cheqd-testnet-6) network.
The next few questions are used to configure Cosmovisor-related options. Read , or choose to install with the default settings.
Do you want Cosmovisor to automatically download binaries for scheduled upgrades? (yes/no) [default: yes]: By default, Cosmovisor will attempt to automatically download new binaries that have passed . You can choose to do this manually if you want more control.
Do you want Cosmovisor to automatically restart after an upgrade? (yes/no) [default: yes]: By default, Cosmovisor will automatically restart the node after an is reached and an upgrade carried out.
Answers to these prompts are saved in the app.toml and /config.toml files, which are written under /home/cheqd/.cheqdnode/config/ by default (but can be different if a different home directory was set above). An explanation of some these settings are available in and the .
Provide a moniker for your cheqd-node [default: <hostname>]:: Moniker is a human-readable name for your cheqd-node. This is NOT the same as your , and is only used to uniquely identify your node for Tendermint P2P address book.
Specify your node's P2P port [default: 26656]:
Specify your node's RPC port [default: 26657]:
Specify minimum gas price [default: 5000ncheq]: Minimum gas prices is the price you are willing to accept as a validator to process a transaction. Values should be entered in format <number>ncheq (e.g., )
Since this can be quite cumbersome and take a really long time, the installer offers the ability to download a recent blockchain snapshot for the selected network from .
If you choose this option, you can step away and return to the installer while it works in the background to complete the rest of the installation. You might want to , since some hosts terminate connection due to inactivity.
Choose binary release version to to.
The installer is designed to terminate the installation process and stop making changes if it encounters an error. If this happens, please reach out to us on our or for how to proceed and recover from errors (if any).
If your scenario is more complex, such as in case of or , please review the guidance under .
❓ The absolute newest block height across the entire network is displayed in the block explorer. Check the or the (depending on which network you've joined) to understand the network-wide latest block height vs your node's delta.
If you're configuring a validator, check out for further configuration steps to carry out.