Tangle Network
Node Operators
Deploying with Docker
Collator Node

Deploying with Docker

A Tangle node can be spun up quickly using Docker. For more information on installing Docker, please visit the official Docker docs (opens in a new tab). When connecting to Tangle on Kusama, it will take a few days to completely sync the embedded relay chain. Make sure that your system meets the requirements which can read here

Parachain Testnet

1. Pull the Tangle Docker image:

Although we can make use of the provided docker-compose file in the Tangle repo (opens in a new tab), we pull the tangle-parachain:main Docker image from so that we can generate and insert our required keys before starting the node.

# Only use "main" if you know what you are doing, it will use the latest and maybe unstable version of the node.

docker pull

2. Create a local directory to store the chain data:

Let us create a directory where we will store all the data for our node. This includes the chain data, keys, and logs.

mkdir /var/lib/tangle/

3. Fetch applicable chainspec(s):

To join the Tangle Test network as collator we need to fetch the appropriate chainspec for the Tangle network. Download the latest chainspec for parachain testnet:

# Fetches chainspec for Tangle network

Please make a reference where you have stored this json file as we will need it in the next steps.

4. Generate and store keys:

We need to generate the required keys for our node. For more information on these keys, please see the Required Keys (opens in a new tab) section. The keys we need to generate include the following:

  • DKG key (Ecdsa)
  • Aura key (Sr25519)
  • Account key (Sr25519)
  • Nimbus key (Sr25519)
  • Rand key (Sr25519)
  • ImOnline key (Sr25519)

Let's now insert our required secret keys, we will not pass the SURI in the command, instead it will be interactive, where you should paste your SURI when the command asks for it.

Account Keys

# it will ask for your suri, enter it.
docker run --rm -it --platform linux/amd64 --network="host" -v "/var/lib/data" \ \
     key insert --base-path /var/lib/tangle/ \
    --chain /data/chainspecs/tangle-parachain.json \
    --scheme Sr25519 \
    --key-type acco

Aura Keys

docker run --rm -it --platform linux/amd64 --network="host" -v "/var/lib/data" \ \
    key insert --base-path /var/lib/tangle/ \
    --chain /data/chainspecs/tangle-parachain.json \
    --scheme Sr25519 \
    --key-type aura

Im-online Keys - these keys are optional (required if you are running as a collator)

docker run --rm -it --platform linux/amd64 --network="host" -v "/var/lib/data" \ \
    key insert --base-path /var/lib/tangle/ \
    --chain /data/chainspecs/tangle-parachain.json \
    --scheme Sr25519 \
    --key-type imon

DKG Keys

docker run --rm -it --platform linux/amd64 --network="host" -v "/var/lib/data" \ \
    tangle-parachain key insert --base-path /data \
    --chain /data/chainspecs/tangle-parachain.json \
    --scheme Ecdsa \
    --key-type wdkg

Nimbus Keys

docker run --rm -it --platform linux/amd64 --network="host" -v "/var/lib/data" \ \
    tangle-parachain key insert --base-path /data \
    --chain /data/chainspecs/tangle-parachain.json \
    --scheme Sr25519 \
    --key-type nmbs

Rand Keys

docker run --rm -it --platform linux/amd64 --network="host" -v "/var/lib/data" \ \
    tangle-parachain key insert --base-path /data \
    --chain /data/chainspecs/tangle-parachain.json \
    --scheme Sr25519 \
    --key-type rand

To ensure you have successfully generated the keys correctly run:

ls ~/webb/tangle/chains/*/keystore
# You should see a some file(s) there, these are the keys.

5. Start Tangle Collator node:

To start the node run the following command:

docker run --platform linux/amd64 --network="host" -v "/var/lib/data" --entrypoint ./tangle-parachain \ \
--base-path=/data \
--chain dev \
--name="YOUR-NODE-NAME" \
--execution wasm \
--wasm-execution compiled \
--trie-cache-size 0 \
-- \
--execution wasm \
--name="YOUR-NODE-NAME (Embedded Relay)"

For an overview of the above flags, please refer to the CLI Usage (opens in a new tab) page of our documentation.

Once Docker pulls the necessary images, your Tangle node will start, displaying lots of information, such as the chain specification, node name, role, genesis state, and more.

2023-03-22 14:55:51 Tangle Parachain
2023-03-22 14:55:51 ✌️  version 0.1.15-54624e3-aarch64-macos
2023-03-22 14:55:51 ❤️  by Webb Technologies Inc., 2017-2023
2023-03-22 14:55:51 📋 Chain specification: Tangle Testnet
2023-03-22 14:55:51 🏷  Node name: cooing-morning-2891
2023-03-22 14:55:51 👤 Role: FULL
2023-03-22 14:55:51 💾 Database: RocksDb at /Users/local/Library/Application Support/tangle-parachain/chains/local_testnet/db/full
2023-03-22 14:55:51 ⛓  Native runtime: tangle-parachain-115 (tangle-parachain-1.tx1.au1)
2023-03-22 14:55:51 Bn254 x5 w3 params
2023-03-22 14:55:51 Verifier params for mixer
2023-03-22 14:55:51 Verifier params for vanchor
2023-03-22 14:55:51 [0] 💸 generated 5 npos voters, 5 from validators and 0 nominators
2023-03-22 14:55:51 [0] 💸 generated 5 npos targets
2023-03-22 14:55:51 [0] 💸 generated 5 npos voters, 5 from validators and 0 nominators
2023-03-22 14:55:51 [0] 💸 generated 5 npos targets
2023-03-22 14:55:51 [0] 💸 new validator set of size 5 has been processed for era 1
2023-03-22 14:55:52 🔨 Initializing Genesis block/state (state: 0xfd16…aefd, header-hash: 0x7c05…a27d)
2023-03-22 14:55:52 👴 Loading GRANDPA authority set from genesis on what appears to be first startup.
2023-03-22 14:55:53 Using default protocol ID "sup" because none is configured in the chain specs
2023-03-22 14:55:53 🏷  Local node identity is: 12D3KooWDaeXbqokqvEMqpJsKBvjt9BUz41uP9tzRkYuky1Wat7Z
2023-03-22 14:55:53 💻 Operating system: macos
2023-03-22 14:55:53 💻 CPU architecture: aarch64
2023-03-22 14:55:53 📦 Highest known block at #0
2023-03-22 14:55:53 〽️ Prometheus exporter started at
2023-03-22 14:55:53 Running JSON-RPC HTTP server: addr=, allowed origins=["http://localhost:*", "*", "https://localhost:*", "*", ""]
2023-03-22 14:55:53 Running JSON-RPC WS server: addr=, allowed origins=["http://localhost:*", "*", "https://localhost:*", "*", ""]

If you followed the installation instructions for Tangle, once synced, you will be connected to peers and see blocks being produced on the Tangle network! Note that in this case you need to also sync to the Polkadot/Kusama relay chain, which might take a few days.

Run via Docker Compose

The docker-compose file will spin up a container running tangle parachain node, but you have to set the following environment variables. Remember to customize your the values depending on your environment and then copy paste this to CLI.


After that run:

docker compose up -d

Update the Client

As Tangle development continues, it will sometimes be necessary to upgrade your node software. Node operators will be notified on our Discord channel when upgrades are available and whether they are necessary (some client upgrades are optional). The upgrade process is straightforward and is the same for a full node or collator.

  1. Stop the docker container:
sudo docker stop `CONTAINER_ID`
  1. Get the latest version of Tangle from the Tangle GitHub Release page (opens in a new tab)

  2. Pull the latest version of Tangle binary by doing docker pull{VERSION_CODE}. Example, if the latest version of Tangle is v0.1.2, then the command would be docker pull

  3. Restart the tangle container and you should have the updated version of the client.

Purge Your Node

If you need a fresh instance of your Tangle node, you can purge your node by removing the associated data directory.

You'll first need to stop the Docker container:

sudo docker stop `CONTAINER_ID`

If you did not use the -v flag to specify a local directory for storing your chain data when you spun up your node, then the data folder is related to the Docker container itself. Therefore, removing the Docker container will remove the chain data.

If you did spin up your node with the -v flag, you will need to purge the specified directory. For example, for the suggested data directly, you can run the following command to purge your parachain node data:

# purges parachain data
sudo rm -rf /data/chains/*

If you ran with parachain node you can run the following command to purge your relay-chain node data:

# purges relay chain data
sudo rm -rf /data/polkadot/*

Now that your chain data has been purged, you can start a new node with a fresh data directory!

Last updated on March 22, 2023