Installing a cheqd node using Debian package releases

Context

This document provides guidance on how to install and configure a node for the cheqd testnet.

Installation steps for cheqd-node .deb

  1. 1.
    For mainnet nodes, use v0.3.1+
    1
    wget https://github.com/cheqd/cheqd-node/releases/download/v0.3.1/cheqd-node_0.3.1_amd64.deb
    Copied!
    For testnet nodes, use v0.4.0:
    1
    wget https://github.com/cheqd/cheqd-node/releases/download/v0.4.0/cheqd-node_0.4.0_amd64.deb
    Copied!
  2. 2.
    Install the package
    For mainnet nodes on v0.3.1+
    1
    sudo dpkg -i cheqd-node_0.3.1_amd64.deb
    Copied!
    For testnet nodes on v0.4.0 (or below):
    1
    sudo dpkg -i cheqd-node_0.4.0_amd64.deb
    Copied!
    As a part of installation cheqd user will be created. By default, HOME directory for the user is /home/cheqd, but it can be changed by setting CHEQD_HOME_DIR environment variable before running dpkg command. Additionnally, a custom logging directory can also be defined by passing the environment variable CHEQD_LOG_DIR (defaults to /home/cheqd/.cheqdnode/log):
    Example custom directories:
    1
    sudo CHEQD_HOME_DIR=/path/to/desired/home/directory dpkg -i cheqd-node_0.3.1_amd64.deb
    Copied!
  3. 3.
    Switch to the cheqd system user
    Always switch to cheqd user before managing node. By default, the node stores configuration files in the home directory for the user that initialises the node. By switching to the special cheqd system user, you can ensure that the configuration files are stored in the system app data directories configured by the Debian package.
    1
    sudo su cheqd
    Copied!
  4. 4.
    Initialise the node configuration files
    The "moniker" for your node is a "friendly" name that will be available to peers on the network in their address book, and allows easily searching a peer's address book.
    1
    cheqd-noded init <node-moniker>
    Copied!
  5. 5.
    Download the genesis file for a persistent chain, such as the cheqd testnet
    Download the genesis.json file for the relevant persistent chain and put it in the $HOME/.cheqdnode/config directory.
    For cheqd mainnet:
    1
    wget -O $HOME/.cheqdnode/config/genesis.json https://raw.githubusercontent.com/cheqd/cheqd-node/main/persistent_chains/mainnet/genesis.json
    Copied!
    For cheqd testnet:
    1
    wget -O $HOME/.cheqdnode/config/genesis.json https://raw.githubusercontent.com/cheqd/cheqd-node/main/persistent_chains/testnet/genesis.json
    Copied!
  6. 6.
    Define the seed configuration for populating the list of peers known by a node
    Update seeds with a comma separated list of seed node addresses specified in seeds.txt for the relevant persistent chain.
    For cheqd mainnet, set the SEEDS environment variable:
    1
    SEEDS=$(wget -qO- https://raw.githubusercontent.com/cheqd/cheqd-node/main/persistent_chains/mainnet/seeds.txt)
    Copied!
    For cheqd testnet, set the SEEDS environment variable:
    1
    SEEDS=$(wget -qO- https://raw.githubusercontent.com/cheqd/cheqd-node/main/persistent_chains/testnet/seeds.txt)
    Copied!
    After the SEEDS variable is defined, pass the values to the cheqd-noded configure tool to set it in the configuration file.
    1
    $ echo $SEEDS
    2
    # Comma separated list should be printed
    3
    4
    $ cheqd-noded configure p2p seeds "$SEEDS"
    Copied!
  7. 7.
    Set gas prices accepted by the node
    Update minimum-gas-prices parameter if you want to use custom value. The default is 25ncheq.
    1
    cheqd-noded configure min-gas-prices "25ncheq"
    Copied!
  8. 8.
    Turn off empty block creation
    By default, the underlying Tendermint consensus creates blocks even when there are no transactions ("empty blocks").
    Turning off empty block creation is an optimisation strategy to limit growth in chain size, although this only works if a majority of the nodes opt-in to this setting.
    1
    cheqd-noded configure create-empty-blocks false
    Copied!
  9. 9.
    Define the external peer-to-peer address
    Unless you are running a node in a sentry/validator two-tier architecture, your node should be reachable on its peer-to-peer (P2P) port by other other nodes. This can be defined by setting the external-address property which defines the externally reachable address. This can be defined using either IP address or DNS name followed by the P2P port (Default: 26656).
    1
    cheqd-noded configure p2p external-address <ip-address-or-dns-name:p2p-port>
    2
    # Example
    3
    # cheqd-noded configure p2p external-address 8.8.8.8:26656
    Copied!
    This is especially important if the node has no public IP address, e.g., if it's in a private subnet with traffic routed via a load balancer or proxy. Without the external-address property, the node will report a private IP address from its own host network interface as its remote_ip, which will be unreachable from the outside world. The node still works in this configuration, but only with limited unidirectional connectivity.
  10. 10.
    Make the RPC endpoint available externally (optional)
    This step is necessary only if you want to allow incoming client application connections to your node. Otherwise, the node will be accessible only locally. Further details about the RPC endpoints is available in the cheqd node setup guide.
    1
    cheqd-noded configure rpc-laddr "tcp:\/\/0.0.0.0:26657"
    Copied!
  11. 11.
    Enable and start the cheqd-noded system service
    If you are prompted for a password for the cheqd user, type exit to logout and then attempt to execute this as a privileged user (with sudo privileges or as root user, if necessary).
    1
    $ systemctl enable cheqd-noded
    2
    Created symlink /etc/systemd/system/multi-user.target.wants/cheqd-noded.service → /lib/systemd/system/cheqd-noded.service.
    3
    4
    $ systemctl start cheqd-noded
    Copied!
    Check that the cheqd-noded service is running. If successfully started, the status output should return Active: active (running)
    1
    systemctl status cheqd-noded
    Copied!

Post-installation checks

Once the cheqd-noded daemon is active and running, check that the node is connected to the cheqd testnet and catching up with the latest updates on the ledger.

Checking node status via terminal

1
cheqd-noded status
Copied!
In the output, look for the text latest_block_height and note the value. Execute the status command above a few times and make sure the value of latest_block_height has increased each time.
The node is fully caught up when the parameter catching_up returns the output false.

Checking node status via the RPC endpoint

An alternative method to check a node's status is via the RPC interface, if it has been configured.
  • Remotely via the RPC interface: cheqd-noded status --node <rpc-address>
  • By opening the JSONRPC over HTTP status page through a web browser: <node-address:rpc-port>/status

Next steps

At this stage, your node would be connected to the cheqd testnet as an observer node. Learn how to configure your node as a validator node to participate in staking rewards, block creation, and governance.