Prerequisites:
Install Go (currently, our builds are done for Golang v1.18)
To build the executable, run:
We have an in-depth guide for making custom Docker image builds.
We also have an in-depth guide on running a localnet with multiple nodes using Docker / Docker Compose.
ℹ️ We provide installation instructions using pre-built Docker images if you just want to setup and use a Docker-based node.
These advanced instructions are intended for developers who want to build their own custom Docker image. You can also build a binary using Golang, or run a Docker-based localnet.
Install Docker pre-requisites below, either as individual installs or using Docker Desktop (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 use Compose v2 syntax. 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 developers running Mac OS with Apple M-series chips, which Docker has special guidance for.
Other issues are due to developers using the legacy docker-compose CLI rather than the new docker compose CLI. If your issues are specifically with Docker Compose, make sure the command used is docker compose (with a space).
Clone the cheqd-node repository from Github. (Github has instructions on how to clone a repo.)
Inspect the Dockerfile to understand build arguments and variables. This is only really necessary if you want to modify the Docker build.
Or, If you want to use Docker buildx engine, look at the usage/configuration in our Github build workflow.
Note: If you're building on a Mac OS system with Apple M-series chips, you should modify the
FROMstatement in the Dockerfile toFROM --platform=linux/amd64 golang:1.18-alpine AS builder. Otherwise, Docker will try to download the Mac OSdarwinimage for the base Golang image and fail during the build process.
If you're planning on passing/modifying a lot of build arguments from their defaults, you can modify the Docker Compose file and the associated environment files to define the build/run-time variables in a one place. This is the recommended method.
Note that a valid Docker Compose file will only have one build and image section, so modify/comment this as necessary. See our instructions for how to use Docker Compose for mainnet/testnet to understand how this works.
Sample command (modify as necessary):
If you don't want to use docker compose build, or build using docker build and then run it using Docker Compose, a sample command you could use is (modify as necessary)
Once you built a Docker image, you can:
Configure a Docker-based node installation for mainnet/testnet
Run a localnet using this custom Docker image
This document provides instructions on how to run a localnet with multiple validator/non-validator nodes. This can be useful if you are developing applications to work on cheqd network, or in automated testing pipelines.
The techniques described here are used in CI/CD contexts, for example, in this repository itself in the test.yml Github workflow.
A clone of the cheqd-node repository
Either a pre-built Docker image downloaded from Github Container Registry, or a custom-built Docker image (the latter is mandatory if you've modified any code in the repository cline).
Docker Engine and Docker Compose (same versions as described in configuration instructions for Docker setup)
A cheqd-node binary to run the network config generation script below.
Our localnet setup instructions are designed to set up a local network with the following node types:
3x validator nodes
1x non-validator/observer node
1x seed node
The definition for this network is described in a localnet Docker Compose file, which can be modified as required for your specific use case. Since it's not possible to cover all possible localnet setups, the following instructions describe the steps necessary to execute a setup similar to that using in our Github test workflow.
Execute the bash script gen-network-config.sh to generate validator keys and node configuration for the node types above.
You may modify the output if you want a different mix of node types.
Import the keys generated using the import-keys.sh bash script:
Modify the docker-compose.yml file if necessary, along with the per-container environment variables under the container-env folder.
The default Docker localnet will configure a running network with a pre-built image or custom image.
The five nodes and corresponding ports set up by the default Docker Compose setup will be:
Validator nodes
validator-0
P2P: 26656
RPC: 26657
validator-1
P2P: 26756
RPC: 26757
validator-2
P2P: 26856
RPC: 26857
validator-3
P2P: 26956
RPC: 26957
Seed node
seed-0
P2P: 27056
RPC: 27057
Observer node
observer-0
P2P: 27156
RPC: 27157
You can tests connection to a node using browser: http://localhost:<rpc_port>. Example for the first node: http://localhost:26657.
Key and corresponding accounts will be placed in the network config folder by the import-keys.sh script, which are used within the nodes configured above.
When connecting using CLI, provide the --home parameter to any CLI command to point to the specific home directory of the corresponding node: --home network-config/validator-x.
See the cheqd CLI guide to learn about the most common CLI commands.