This document describes the hardware and software pre-requisites for setting up a new cheqd-node instance and joining the existing testnet/mainnet. The recommended installation method is to use the interactive installer script.
Alternative installation methods and a developer guide to building from scratch are covered at the end of this page.
For most nodes, the RAM/vCPU requirements are relatively static and do not change over time. However, the disk storage space needs to grow as the chain grows and will evolve over time.
It is recommended to mount disk storage for blockchain data as an expandable volume/partition separate from your root partition. This allows you mount the node data/configuration path on /home (for example) and increase the storage if necessary independent of the root / partition since hosting providers typically force an increase in CPU/RAM specifications to grow the root partition.
Extended information on recommended hardware requirements is available in Tendermint documentation. The figures below have been updated from the default Tendermint recommendations to account for current cheqd network chain size, real-world usage accounting for requests nodes need to handle, etc.
4-8 GB RAM (2 GB RAM minimum)
x64 2.0 GHz 2-4 vCPU or equivalent (x64 1.4 GHz 1 vCPU or equivalent minimum)
650 GB SSD (500 GB minimum)
⚠️ Storage requirements for the blockchain grows with time. Therefore, these minimum storage figures are expected to increase over time. Read our validator guide for "pruning" settings to optimise storage consumed.
We recommend using a storage path that can be kept persistent and restored/remounted (if necessary) for the configuration, data, and log directories associated with a node. This allows a node to be restored along with configuration files such as node keys and for the node's copy of the ledger to be restored without triggering a full chain sync.
The default directory location for cheqd-node installations is $HOME/.cheqdnode, which computes to /home/cheqd/.cheqdnode when using the interactive installer. Custom paths can be defined if desired.
Our packaged releases are currently compiled and tested for Ubuntu 20.04 LTS, which is the recommended operating system for installation using interactive installer or binaries.
For other operating systems, we recommend using pre-built Docker image releases for cheqd-node.
We plan on supporting other operating systems in the future, based on demand for specific platforms by the community.
To function properly, cheqd-node requires two types of ports to be configured. Depending on the setup, you may also need to configure firewall rules to allow the correct ingress/egress traffic.
Node operators should ensure there are no existing services running on these ports before proceeding with installation.
The P2P port is used for peer-to-peer communication between nodes. This port is used for your node to discover and connect to other nodes on the network. It should allow traffic to/from any IP address range.
By default, the P2P port is set to 26656.
Inbound TCP connections on port 26656 (or your custom port) should be allowed from any IP address range.
Outbound TCP connections must be allowed on all ports to any IP address range.
The default P2P port can be changed in $HOME/.cheqdnode/config/config.toml.
Further details on how P2P settings work is defined in Tendermint documentation.
The RPC port is intended to be used by client applications as well as the cheqd-node CLI. Your RPC port must be active and available on localhost to be able to use the CLI. It is up to a node operator whether they want to expose the RPC port to public internet.
The RPC endpoints for a node provide REST, JSONRPC over HTTP, and JSONRPC over WebSockets. These API endpoints can provide useful information for node operators, such as healthchecks, network information, validator information etc.
By default, the RPC port is set to 26657
Inbound and outbound TCP connections should be allowed from destinations desired by the node operator. The default is to allow this from any IPv4 address range.
TLS for the RPC port can also be setup separately. Currently, TLS setup is not automatically carried out in the install process described below.
The default RPC port can be changed in $HOME/.cheqdnode/config/config.toml.
In addition to the P2P/RPC ports above, you need to allow the following ports in terms of firewall access for the node to function correctly:
Domain Name System (DNS): Allow outbound traffic on TCP & UDP port 53 which allows your node to make DNS queries. Without this, your node will fail to make DNS lookups necessary to reach the peer-to-peer traffic ports for other nodes.
Network Time Protocol (NTP): Allow outbound traffic on UDP port 123, which allows the NTP service to keep your system clock synchronised. Without this, if your node's system clock drifts too far away from actual time in your node's timezone, it can reject peer-to-peer connectivity.
Tendermint allows more complex setups in production, where the ingress/egress to a validator node is proxied behind a "sentry" node.
While this setup is not compulsory, node operators with higher stakes or a need to have more robust network security may consider setting up a sentry-validator node architecture.
The interactive installer is designed to setup/configure node installation as a service that runs on a virtual machine. This is the recommended setup for most scenarios when running as a validator. A validator node is expected to run 24/7 for network stability and security, and therefore cannot be autoscaled up/down across multiple instances.
If you're not running a validator node, or if you want more advanced control on your setup, installing with a Docker image is also supported. This method is also useful for running a localnet or when running a node on non-Linux systems for development purposes.
Tendermint documentation has best practices for running a Cosmos node in production.
Сosmovisor could be used for automatic upgrades; however in our testing so far this method has not been reliable and is therefore currently not recommended.
We provide for installation by those who want to run on Docker-based systems.
Docker-based installations are useful when running non-validator (observer) nodes that can be auto-scaled according to demand, or if you're a developer who setup a localnet / access node CLI without running a node.
⚠️ It is NOT recommended to run a validator node using Docker since you need to be absolutely certain about not running two Docker containers as validator nodes simultaneously. If two Docker containers with the same validator keys are active at the same time, this could be perceived by the network as a validator compromise / double-signing infraction and result in jailing / slashing.
pre-requisites below, either as individual installs or using (if running on a developer machine):
Docker Engine v20.10.x and above (use docker -v to check)
Docker Compose v2.3.x and above (use docker compose version to check)
Our Docker Compose files . The primary difference in usage is that Docker Compose's new implementation uses docker compose commands (with a space), rather than the legacy docker-compose although they are supposed to be drop-in replacements for each other.
Most issues with Docker that get raised with us are typically with for.
Other issues are due to developers . If your issues are specifically with Docker Compose, make sure the command used is docker compose (with a space).
Both of the .env files are signposted with the REQUIRED and OPTIONAL parameters that can be defined. You must fill out the required configuration parameters.
Once the environment variable files are edited, bringing up a Docker container is as simple as:
If you decide not to use the Docker Compose method, you'll need to configure node settings and volumes for the container manually.
Once you've configured these manually, start using
Alternatively, if you want to just start with the bash terminal without actually starting a node, you could use:
To stop a detached container that was started using Docker Compose, use:
If you also want to remove the container volumes when stopping, add the --volumes flag to the command:
Be careful with removing volumes, since critical data such as node/validator keys will also be removed when volumes are removed. There's no way to get these back, unless you've backed them up independently.
We have additional guides for the following advanced usage scenarios:
Pull a (replace latest with a different version tag if you want to pull something other than the latest version):
We provide . This is broken down into three files that need to be modified with the configuration parameters:
: Docker Compose file
: Environment variables used in docker-compose.yml
: Environment variables used inside the cheqd-node container
Note: The file paths above for the -f and --env-file parameter are relative to the . Please modify the file paths for the correct relative/absolute paths on the system where you are executing the commands.
to create custom images
with multiple nodes to simulate a network
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 hardware, software, and networking pre-requisites for nodes 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 configures Cosmovisor 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.
Network snapshot server (optional): If requested by the user, the script will fetch latest network snapshots published on snapshots.cheqd.net and then download snapshot files from the snapshot CDN endpoint (snapshots-cdn.cheqd.net)
⚠️ The guidance below is intended for straightforward new installations or upgrades.
If your scenario is more complex, such as in case of upgrading a validator or moving a validator, please review the guidance under our validator guide.
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.
Join either the existing mainnet (chain ID: cheqd-mainnet-1) or testnet (chain ID: cheqd-testnet-6) network.
The next few questions are used to configure Cosmovisor-related options. Read an explanation of Cosmovisor configuration options in Cosmos SDK documentation, or choose to install with the default settings.
Install cheqd-noded using Cosmovisor? (yes/no) [default: yes]: Use Cosmovisor to run node
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 software upgrade proposals voted on the network. 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 upgrade height is reached and an upgrade carried out.
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.
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 requirements for running a node and the validator guide.
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 validator name, and is only used to uniquely identify your node for Tendermint P2P address book.
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 your node's P2P port [default: 26656]: Tendermint peer-to-peer traffic port
Specify your node's RPC port [default: 26657]: Tendermint RPC port
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 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., 5000ncheq)
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.
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 snapshots.cheqd.net.
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 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 change settings in your SSH client / server to keep SSH connections alive, since some hosts terminate connection due to inactivity.
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.
Choose binary release version to upgrade the node to.
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 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 community Slack or Discord for how to proceed and recover from errors (if any).
⚠️ The guidance below is intended for straightforward new installations or upgrades.
If your scenario is more complex, such as in case of upgrading a validator or moving a validator, please review the guidance under our validator guide.
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.
❓ The absolute newest block height across the entire network is displayed in the block explorer. Check the mainnet explorer or the testnet explorer (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 our validator guide for further configuration steps to carry out.