Skip to main content

Deploy your replicator node

In this page, we introduce instructions to deploy your Carmentis node. Whatever the manner you choose, the deployment is organized in two steps: (1) setup a node configuration and (2) launch the node based on the provided configuration.

Difference between replicator and validator

A replicator node can be launched with a minimal configuration by running only a node. Validator nodes, however, are expected to run both a node and an operator. In theory, we encourage to install a node and an operator in distinct servers to improve security and modularity. In practice, since we are using Docker, both node and operator can be installed on the same server, this configuration is called validator set up. For more convenience, we provide two distinct documentation pages:

Prerequisites​

  • For replicator nodes, a laptop is enough even more when testing the network. In production, we recommend a server with at least 2 cores and 4GB of RAM.
  • For validator nodes, we recommend a server with at least 2 cores and 4GB of RAM. The server should be externally accessible with a public IP address and a domain name (e.g., node.your-domain-name) pointing to your server. We do not assume the server to handle TLS as we use a reverse proxy server (like Caddy) to handle TLS while it is not mandatory.

Set up node configuration​

Docker installation​

Docker is intensively used in our procedure to install, configure and run components. Follow the instructions on the official Docker documentation to install Docker. To check your installation, run docker run --rm hello-world.

Docker compose binary name

Be careful, old docker versions are using docker-compose name.

Set up node configuration using CLI​

We provide a CLI to set up the configuration quickly.

Step 1: Install npm and the CLI​

The first step is to install the node package manager (npm).

sudo apt update && sudo apt upgrade -y && sudo apt install npm && sudo npm i -g @cmts-dev/carmentis-cli

Step 2: Init the CLI​

Before to proceed to the generation, you have to initialize the CLI, notably by importing the reference networks:

cmts networks import

You can list the loaded networks using the cmts networks list command.

Step 3: Generate the config​

To generate the configuration of your node, execute the following command and answer to the response interactively (replace the $PATH_TO_GENERATE_CONFIG with the path where the configuration is generated):

cmts node init-config --home $PATH_TO_GENERATE_CONFIG

Step 4: Run the node​

To run the node, execute the following command (replace the $PATH_TO_GENERATE_CONFIG with the path where the configuration has been generated):

cd $PATH_TO_GENERATE_CONFIG && docker compose up -d

Set up node configuration manually​

In this section, we explain how to set up the node configuration manually.

Below is shown the expected directory structure of the node configuration when the node is running. Most of them are generated but some configuration are still required.

.
├── abci <--- Automatically generated
| ├── db
| ├── microblocks
│ └── snapshots
├── cometbft <--- Generated by `cometbft init` at Step 2
│ ├── config
| | └── config.toml // Edited at Step 3
| └── data
├── config.toml // Edited at Step 3
├── Caddyfile // Edited at Step 3 (optional if not using caddy)
└── docker-compose.yml // Edited at Step 3

Install go and CometBFT​

First, you have to install go on your system. We highly recommend you to use the latest version of go but we provide the installation command to install go 1.25.1 which should be sufficient:

wget https://go.dev/dl/go1.25.1.linux-amd64.tar.gz && sudo rm -rf /usr/local/go && sudo tar -C /usr/local -xzf go1.25.1.linux-amd64.tar.gz

Then, update your PATH (edit your .bashrc or your equivalent file to persist the modification):

export PATH=$PATH:/usr/local/go/bin:$HOME/go/bin

To install CometBFT, run the following command:

go install github.com/cometbft/cometbft/cmd/cometbft@v0.38
CometBFT v0.38

The current version requires CometBFT v0.38.

Check that cometbft is correctly installed by executing cometbft --help.

note

You might need to restart your terminal to apply the changes.

Create the configuration​

Start by generating the initial configuration which includes the private key pair of your node:

cometbft init --home ./cometbft

A new cometbft folder is created in the current directory, containing the configuration files for CometBFT.

Update the genesis.json file in the cometbft configuration: You have to download the genesis file of the network you want to join. Assuming curl and jq are installed on your (linux) system, you can download the genesis file using the following command below. The curl and jq packages can be installed easily using sudo apt install curl jq. Note that we use the ares.testnet.carmentis.io server but any server connected to the network can be used:

# This command displays the genesis file on your terminal 
curl https://ares.testnet.carmentis.io/genesis  | jq .result.genesis

# This command saves the genesis file at ./cometbft/config/genesis.json
curl https://ares.testnet.carmentis.io/genesis  | jq .result.genesis > ./cometbft/config/genesis.json

Update the config.toml file in the cometbft configuration: By default, CometBFT comes with a configuration that needs to be adapted to the network you want to join. To proceed, open the configuration file located at cometbft/config/config.toml (if generated as explained in this documentation) and edit the configuration file. The configuration file is described in the official CometBFT documentation. We introduce you below the most interesting parameters to edit below:

# Put the name of your node. This name will be used as a human-friendly name.
moniker = "your-name"
[p2p]
# A peer is consisting of the identifier of the node followed by its domain name or ip address and the p2p port (26656 by default).
persistent_peers = "e476e89ce33a9c72d9d3ff6bcb6f51d4f28c98d8@apollo.testnet.carmentis.io:26656,17065b42305763be6c416b400f90f051a7bf5459@ares.testnet.carmentis.io:26656"
[statesync]
# When enabled, the node uses snapshots to speedup synchronization with several order of magnitude.
# We highly encourage you to enable this parameter when the chain is more than few thousands long.
enable = true
rpc_servers = "http://ares.testnet.carmentis.io:26657,http://athena.testnet.carmentis.io:26657"
trust_hash = "16F13D886398B059EA7CC4DD9E4F5B0BE8EA29CBD12DB6A98D7DF6B3AA988F0A"
# Be sure to have the latest trust height and hash to prevent any outdated sync issue. See below.
trust_height = 23
[rpc]
# By default, CometBFT rejects connections from other websites because of strict CORS policy. By adding "*", we allow other websites to reach the ABCI query of node.
cors_allowed_origins = ["*"]
...
Latest trust_hash and trust_height values

We provide below the following latest values from ares.testnet.carmentis.io and apollo.testnet.carmentis.io:

  • For the statesync.persistent_peers field: Loading...,Loading...
  • For the statesync.trust_height field: Loading...
  • For the statesync.trust_hash field: Loading...

Create the config.toml file of the ABCI server: The ABCI server is used by CometBFT to model the logic of Carmentis within the CometBFT server. This ABCI server needs a configuration file whose the configuration documentation can be found here. This file has to be created next to the cometbft folder, we refer you to the tree structure below. We provide you a ready-to-use configuration for your node. Be aware that this configuration might not be compatible with your configuration!

[genesis_snapshot]
# Endpoint used when the genesis snapshot has to be fetched. The endpoint above is enough most of the time.
rpc_endpoint = "http://ares.testnet.carmentis.io:26657"
[cometbft]
# The *publicly accessible* RPC endpoint used by other in the network to contact the CometBFT server
#  endpoint.
exposed_rpc_endpoint = "https://node.your-domain-name"
[paths]
cometbft_home = "/cometbft"
storage = "/abci"
[snapshots]
snapshot_block_period = 5
block_history_before_snapshot = 0
max_snapshots = 10
[abci.grpc]
port = 26658
[abci.query.rest]
port = 26659

Create the docker-compose.yml file: This file describes the containers that Docker will launch to run the node. You can find below the docker-compose.yml file that we use to deploy our node. In our infrastructure, we delegate the TLS certificates management and renewal to Caddyserver. Since other reverse proxy servers can be used, we let you with two deployment options: With and without Caddy. Not that if you choose to not use Caddy, you might need to adapt the docker-compose.yml file to fit your context. Whatever your choice is, we are not responsible for any misconfiguration of your node! We encourage to read the official Docker documentation to understand how to use the docker-compose.yml file but also to read the security considerations section.

To set up the node with Caddy, you have to create the docker-compose.yml and Caddyfile files.

docker-compose.yml
Loading...

Create the Caddyfile file: This file describes the reverse proxy configuration. Replace the <your-domain-name> placeholder by the domain name of your node. You can find below the Caddyfile file that we use to deploy our node.

Caddyfile
Loading...

Launch the node​

By running the following command, the node will be launched.

docker compose up -d

Next steps​

Checking node status​

To check if the node status is alive, you can proceed to the domain name associated where the node is deployed. A list of endpoints should be displayed. Check one of our nodes, for example, at https://ares.testnet.carmentis.io. Then, click on the status endpoint to check the node status and search for the is_catching_up and latest_block_height fields. If the value of is_catching_up is true, the node is still catching up with the blockchain. If the value is false and latest_block_height is defined, the node is up, synchronized and running.

Access to the logs​

To check the logs of the node, you can use docker using the docker compose logs -f command.

Stop the node​

To stop the node, run the following command:

docker compose down

Reset the node from scratch​

To reset the node from scratch (like a fresh node), you can use the following command:

# down the ABCI and CometBFT containers
docker compose down node-abci node-cometbft

# clear the local data (be careful, this command will delete all the data, requiring a new synchronization)
cometbft unsafe-reset-all --home ./cometbft && rm -Rf abci 

# restart the node
docker compose up -d

Update the CLI​

To keep your CLI up-to-date, execute the following method:

npm update -g @cmts-dev/carmentis-cli

Security considerations​

Based on the CometBFT documentation, for security reasons, the port (26658 by default) of the ABCI server handling CometBFT requests SHOULD NEVER be exposed (except for the CometBFT server).

Troubleshooting​

The sudo command is not found

The sudo command does not exist when logged as root. Either log in as a regular user to execute the commands or adapt the command by removing the sudo.

The curl and/or jq commands are not found

Ensure that you have installed curl and jq on your system using the following command:

sudo apt install curl jq
Docker not permitted (permission denired while trying to connect to the docker API at unix:///var/run/docker.sock)

In a fresh install of Docker, you might be unable to execute the docker run --rm hello-world command. To solve this issue, we highly recommend you to follow the official Docker documentation for post-installations. For more convinience, you can run the following commands but remember to check the Official Docker documentation:

sudo groupadd docker
sudo usermod -aG docker $USER
newgrp docker
docker run --rm hello-world
The docker-compose command is not found

Have you tried docker compose?