Run an Appchain Node Using Docker¶

Introduction¶

Running a Tanssi-powered appchain node allows you to connect to and interact with the appchain using your infrastructure via either HTTP or WebSocket protocols.

Nodes store block data and network state. However, developers can run different kinds of nodes:

• Full Archive Node - a node storing the entire block data and network state at all block heights. Such nodes are helpful when querying historical data from old blocks. However, a full archive node takes up a lot of space

• Full Pruned Node - a node storing block data and network state up to some specific number of blocks before the current block height. Such nodes are helpful when querying recent data or submitting transactions through your infrastructure. They require much less space than an archival node but don't store the full network state

In this guide, you'll learn how to quickly spin up a Tanssi appchain node using Docker on a Linux computer. However, it can be adapted to other operating systems.

Checking Prerequisites¶

Installing Docker¶

To get started, you'll need access to a computer running a Linux OS and install Docker.

Run the following command to install Docker on a Linux Ubuntu platform:

sudo apt-get install docker-ce docker-ce-cli containerd.io docker-buildx-plugin docker-compose-plugin

And the following command to check the installation:

sudo docker run hello-world

This is what a successful execution in the terminal looks like:

Getting Specifications Files¶

An appchain node needs information about two different blockchains to run properly: the appchain and the Tanssi orchestration chain.

That information is a file called chain specifications, and it holds, among other things, the genesis state of the blockchain, allowing the node to verify and sync properly the blocks and state it receives from other nodes.

To get the Tanssi specifications file, execute the following command:

wget https://raw.githubusercontent.com/moondance-labs/tanssi/75e576add204abd321c48cded556c8de14d65618/chains/orchestrator-relays/node/tanssi-relay-service/chain-specs/starlight-raw-specs.json

wget https://raw.githubusercontent.com/moondance-labs/tanssi/75e576add204abd321c48cded556c8de14d65618/chains/orchestrator-relays/node/tanssi-relay-service/chain-specs/dancelight-raw-specs.json

To get the appchain specification file, download it from the dashboard in the dApp by clicking the Network Data link

Setup the Data Directory¶

Running a sequencer or an appchain node require syncing with two chains: the Tanssi orchestration chain and the appchain it is working for.

Run the following command to create the directory where your node will store the databases containing blocks and chain states:

mkdir /var/lib/tanssi-data

mkdir /var/lib/dancelight-data

Set the folder's ownership to the account that will run the Docker image to ensure writing permission:

chown INSERT_DOCKER_USER /var/lib/tanssi-data

chown INSERT_DOCKER_USER /var/lib/dancelight-data

Or run the following command if you want to run the sequencer with the current logged-in user:

sudo chown -R $(id -u):$(id -g) /var/lib/tanssi-data

sudo chown -R $(id -u):$(id -g) /var/lib/dancelight-data

Move the chain specification file to the folder:

mv ./starlight-raw-specs.json /var/lib/tanssi-data

mv ./dancelight-raw-specs.json /var/lib/dancelight-data

Pulling the Docker Image¶

Two Docker images are built and published as part of the automated deployment process for every release: one for EVM-compatible appchains and the other for Substrate appchains.

These Docker images include all the binary files required to run the latest stable release of the client node.

Depending on the type of appchain you want to run the node for, pull the corresponding image.

EVM-Compatible Appchains¶

If the Tanssi-powered appchain was registered in the dApp choosing the EVM template or uploading a custom specification representing a Tanssi EVM-compatible appchain, then execute the following command to pull the Docker image:

docker pull moondancelabs/container-chain-evm-template

docker pull moondancelabs/container-chain-evm-template

The command will download and extract the image and show the status upon execution:

Simple Substrate Appchains¶

If the appchain was registered in the dApp choosing the basic Substrate template or uploading a custom specification file representing a Substrate appchain, then execute the following command to pull the Docker image:

docker pull moondancelabs/container-chain-simple-template

docker pull moondancelabs/container-chain-simple-template

The command will download and extract the image and show the status upon execution, showing a similar output as the previous terminal image.

Start-Up Command¶

To spin up your node, you must run the Docker image with the docker run command. Note that you'll need to modify the following parameters:

• Appchain specs file - replace INSERT_YOUR_APPCHAIN_SPECS_FILE with your appchain specs file name, downloaded in the Getting Specifications Files step.
• Bootnode - a bootnode is a full archive node that is used to sync the network from scratch. You'll need to retrieve your Tanssi network bootnode and replace INSERT_YOUR_NETWORK_BOOTNODES with the actual bootnode information.

docker run --network="host" -v "/var/lib/tanssi-data:/data" \
-u $(id -u ${USER}):$(id -g ${USER}) \
moondancelabs/container-chain-evm-template \
--chain=INSERT_YOUR_APPCHAIN_SPECS_FILE \
--rpc-port=9944 \
--name=appchain \
--state-pruning=archive \
--blocks-pruning=archive \
--database=paritydb \
--unsafe-rpc-external \
--bootnodes=INSERT_YOUR_NETWORK_BOOTNODES \
-- \
--name=relay \
--chain=/data/starlight-raw-specs.json \
--rpc-port=9945 \
--sync=fast \
--database=paritydb \
--bootnodes=/dns4/deo-tanssi-boot-1.rv.tanssi.network/tcp/30334/p2p/12D3KooWNQ1cddxwvnZZUBG2gtByn9hirVGEn2yR37ztnGSi1VHu \
--bootnodes=/dns4/fro-tanssi-boot-1.rv.tanssi.network/tcp/30334/p2p/12D3KooWS3kv4PyNTxKS8CBxZsVrhMcNcXgxqVUHLrXixuz4DaSR \
--bootnodes=/dns4/qcl-tanssi-boot-1.rv.tanssi.network/tcp/30334/p2p/12D3KooWFDUJ1QZn18tmeJJZU4e6JbyQrLiAp4Xz7ongKzoSjadg \
--bootnodes=/dns4/qco-tanssi-boot-1.rv.tanssi.network/tcp/30334/p2p/12D3KooWBzJzAdAKNVXcsvfL3nHH8BSocNvxz7A8PkRAAJhTuQNm \
--bootnodes=/dns4/uko-tanssi-boot-1.rv.tanssi.network/tcp/30334/p2p/12D3KooWAexWR4uyhVPyxqPBNhhepJ5jRqUa885mu5dKPPVHSfpC

docker run --network="host" -v "/var/lib/tanssi-data:/data" \
-u $(id -u ${USER}):$(id -g ${USER}) \
moondancelabs/container-chain-simple-template \
--chain=INSERT_YOUR_APPCHAIN_SPECS_FILE \
--rpc-port=9944 \
--name=appchain \
--state-pruning=archive \
--blocks-pruning=archive \
--database=paritydb \
--unsafe-rpc-external \
--bootnodes=INSERT_YOUR_NETWORK_BOOTNODES \
-- \
--name=relay \
--chain=/data/starlight-raw-specs.json \
--rpc-port=9945 \
--sync=fast \
--database=paritydb \
--bootnodes=/dns4/deo-tanssi-boot-1.rv.tanssi.network/tcp/30334/p2p/12D3KooWNQ1cddxwvnZZUBG2gtByn9hirVGEn2yR37ztnGSi1VHu \
--bootnodes=/dns4/fro-tanssi-boot-1.rv.tanssi.network/tcp/30334/p2p/12D3KooWS3kv4PyNTxKS8CBxZsVrhMcNcXgxqVUHLrXixuz4DaSR \
--bootnodes=/dns4/qcl-tanssi-boot-1.rv.tanssi.network/tcp/30334/p2p/12D3KooWFDUJ1QZn18tmeJJZU4e6JbyQrLiAp4Xz7ongKzoSjadg \
--bootnodes=/dns4/qco-tanssi-boot-1.rv.tanssi.network/tcp/30334/p2p/12D3KooWBzJzAdAKNVXcsvfL3nHH8BSocNvxz7A8PkRAAJhTuQNm \
--bootnodes=/dns4/uko-tanssi-boot-1.rv.tanssi.network/tcp/30334/p2p/12D3KooWAexWR4uyhVPyxqPBNhhepJ5jRqUa885mu5dKPPVHSfpC

docker run --network="host" -v "/var/lib/dancelight-data:/data" \
-u $(id -u ${USER}):$(id -g ${USER}) \
moondancelabs/container-chain-evm-template \
--chain=INSERT_YOUR_APPCHAIN_SPECS_FILE \
--rpc-port=9944 \
--name=appchain \
--state-pruning=archive \
--blocks-pruning=archive \
--database=paritydb \
--unsafe-rpc-external \
--bootnodes=INSERT_YOUR_NETWORK_BOOTNODES \
-- \
--name=relay \
--chain=/data/dancelight-raw-specs.json \
--rpc-port=9945 \
--sync=fast \
--database=paritydb \
--bootnodes=/dns4/qco-dancelight-boot-1.rv.dancelight.tanssi.network/tcp/30334/p2p/12D3KooWCekAqk5hv2fZprhqVz8povpUKdJEiHSd3MALVDWNPFzY \
--bootnodes=/dns4/qco-dancelight-rpc-1.rv.dancelight.tanssi.network/tcp/30334/p2p/12D3KooWEwhUb3tVR5VhRBEqyH7S5hMpFoGJ9Anf31hGw7gpqoQY \
--bootnodes=/dns4/ukl-dancelight-rpc-1.rv.dancelight.tanssi.network/tcp/30334/p2p/12D3KooWPbVtdaGhcuDTTQ8giTUtGTEcUVWRg8SDWGdJEeYeyZcT

docker run --network="host" -v "/var/lib/dancelight-data:/data" \
-u $(id -u ${USER}):$(id -g ${USER}) \
moondancelabs/container-chain-simple-template \
--chain=INSERT_YOUR_APPCHAIN_SPECS_FILE \
--rpc-port=9944 \
--name=appchain \
--state-pruning=archive \
--blocks-pruning=archive \
--database=paritydb \
--unsafe-rpc-external \
--bootnodes=INSERT_YOUR_NETWORK_BOOTNODES \
-- \
--name=relay \
--chain=/data/dancelight-raw-specs.json \
--rpc-port=9945 \
--sync=fast \
--database=paritydb \
--bootnodes=/dns4/qco-dancelight-boot-1.rv.dancelight.tanssi.network/tcp/30334/p2p/12D3KooWCekAqk5hv2fZprhqVz8povpUKdJEiHSd3MALVDWNPFzY \
--bootnodes=/dns4/qco-dancelight-rpc-1.rv.dancelight.tanssi.network/tcp/30334/p2p/12D3KooWEwhUb3tVR5VhRBEqyH7S5hMpFoGJ9Anf31hGw7gpqoQY \
--bootnodes=/dns4/ukl-dancelight-rpc-1.rv.dancelight.tanssi.network/tcp/30334/p2p/12D3KooWPbVtdaGhcuDTTQ8giTUtGTEcUVWRg8SDWGdJEeYeyZcT

Fetching Bootnode Information¶

Bootnode information can be read directly from Tanssi itself. For example, you can use the developer portal to get the bootnodes for a specific network in Dancelight.

To do so, take the following steps:

1. Select dataPreservers as the module to query
2. Set the storage query to bootNodes
3. Provide your Tanssi network ID
4. Click on the + sign

Full Node Example for Demo EVM Appchain¶

The following example spins up a full archive RPC node for the demo EVM network deployed on Dancelight with an ID of 2001. This example assumes that the specs files were downloaded and are located in the data folder.

docker run --network="host" -v "/var/lib/dancelight-data:/data" \
-u $(id -u ${USER}):$(id -g ${USER}) \
moondancelabs/container-chain-evm-template \
--chain=/data/container-2001-raw-specs.json \
--rpc-port=9944 \
--name=demoAppchain \
--state-pruning=archive \
--blocks-pruning=archive \
--database=paritydb \
--unsafe-rpc-external \
--bootnodes=/dns4/ukl-dancelight-2001-rpc-1.rv.dancelight.tanssi.network/tcp/30333/p2p/12D3KooWKDotMgTRpURvoZHsLWP4K9ymhkBByi1EJjMQAnCmqg8E \
--bootnodes=/dns4/qco-dancelight-2001-rpc-1.rv.dancelight.tanssi.network/tcp/30333/p2p/12D3KooWB3kqqNhYgGtGbsdtgD18wUoFVeuXVXgWLXTFs91RNgAx \
-- \
--chain=/data/dancelight-raw-specs.json \
--rpc-port=9945 \
--name=relay \
--sync=fast \
--database=paritydb \
--bootnodes=/dns4/qco-dancelight-boot-1.rv.dancelight.tanssi.network/tcp/30334/p2p/12D3KooWCekAqk5hv2fZprhqVz8povpUKdJEiHSd3MALVDWNPFzY \
--bootnodes=/dns4/qco-dancelight-rpc-1.rv.dancelight.tanssi.network/tcp/30334/p2p/12D3KooWEwhUb3tVR5VhRBEqyH7S5hMpFoGJ9Anf31hGw7gpqoQY \
--bootnodes=/dns4/ukl-dancelight-rpc-1.rv.dancelight.tanssi.network/tcp/30334/p2p/12D3KooWPbVtdaGhcuDTTQ8giTUtGTEcUVWRg8SDWGdJEeYeyZcT

Run Flags¶

The flags used in the docker run command can be adjusted according to your preferences and hardware configuration. The following ones are some of the most note-worthy:

• --name INSERT_NAME - a human-readable name for this node
• --rpc-port INSERT_PORT - specifies the JSON-RPC TCP port the node listens on
• --unsafe-rpc-external - exposes the RPC service on all the interfaces
• --state-pruning INSERT_STATE_PRUNING_TYPE - specifies when the Tanssi-powered network state should be removed from the database. The pruning type can be either archive (which makes the node behave as a full node keeping all the state), archive-canonical (which keeps only the state of finalized blocks), or any number (representing the number of blocks whose states are kept)
• --blocks-pruning INSERT_BLOCKS_PRUNING_TYPE - specifies how many blocks should be kept in the database. The pruning type can be either archive (which makes the node behave as a full node keeping all the blocks), archive-canonical (which keeps only finalized blocks), or any number (representing the amount of finalized blocks to keep)
• --detailed-log-output - enables detailed log output

For a complete list of available flags, their description, and possible values, run the following command:

docker run -ti moondancelabs/container-chain-evm-template --help

docker run -ti moondancelabs/container-chain-simple-template --help

Syncing Your Node¶

Once your node spins up, the syncing process displays a lot of log information from both the node and the Tanssi appchain. Some errors are expected to be displayed at the beginning of the process, disappearing once the chain gets synced to the last block.