In this tutorial, you will learn how to use a set of Docker-based tools and pre-configured setups to deploy your own (hornet-based) Chrysalis Tangle in "one click" to cloud environments or platforms.
IOTA mainnet and devnet are public IOTA Networks where you can develop your own applications. Due to scalability or data locality reasons, sometimes it is also necessary to run your own local IOTA Tangle (aka Private Tangle). In the future, the (child) Tangle might also be anchored to the IOTA mainnet, through Data Sharding (a feature currently under research and development by the IOTA Foundation). To automate and simplify the deployment of a Chrysalis Tangle, some tools, publicly available in the one-click-tangle repository, have been developed. Additionally, the IOTA Foundation has integrated them for use in the AWS Marketplace and, in the future, on other Cloud marketplaces.
The figure below depicts a minimum viable deployment architecture of a Chrysalis Tangle using Docker.
There are three main nodes identified:
The Coordinator: This node emits milestones periodically and has to be bootstrapped and set up appropriately. With the IOTA 2.0 update, the Coordinator will no longer be needed as explained here.
The Spammer: A node that periodically sends messages to your Tangle, thus enabling a minimal message load to support transaction approval as per the IOTA protocol.
The Regular Hornet Node (
node1): An initial node that is exposed to the outside through the IOTA protocol (port
14265) to be the recipient of messages or to peer with other Nodes (through port
15600) that can later join your Tangle.
These three nodes are peered amongst each other as our architecture is based on Docker, so that each node runs within a Docker Container and all containers are attached to the same network named
In addition, to facilitate adding extra nodes to your Tangle, an autopeering entry node is automatically created. Actually, the
Spammer and the
node1 enable by default autopeering so that they can be peered with any extra node later added. The autopeering entry node listens on the UDP port
In addition, to make your Tangle easier to use, a Tangle Explorer can be deployed, conveniently, similar to the one at https://explorer.iota.org. As a result, all the participants in the network are able to browse and visualize messages or IOTA Streams channels. The Tangle Explorer deployment involves two different containers, one with the REST API listening at port
4000 and one with the Web Application exposed to the host at port
8082. The Tangle Explorer also uses MQTT to watch what is happening on your Tangle. This is the rationale for having a connection between the Explorer's REST API Container and the Hornet Node through port
The Hornet Dashboard (available through HTTP port
8081) is also useful as a way to monitor and ensure that your Tangle Nodes are in sync and performing well.
The summary of containers that shall be running and the exposed (actually in use) Docker ports is as follows:
|Component||Container name||Docker Ports in use|
|Hornet Initial Node|
|Autopeering Entry N.|
|Explorer Web App|
The network policies for those containers should be configured as follows:
|Component||Container name||Outgoing Traffic To|
|Hornet Initial Node|
|Autopeering Entry N.||any autopeered node (|
|Explorer Web App|
|Container name||Port||Incoming Traffic from|
|outside clients, |
|other (auto)peers, |
|any autopeered node|
The summary of services exposed to the outside world (through the host) is as follows:
|Service||Container name||Host TCP Port||Host UDP Port|
|Explorer Web App|
The deployment architecture described above can be easily transitioned to production-ready by incorporating a reverse proxy leveraging NGINX. As a result, the amount of ports exposed to the outside world can be reduced or load balancing between the nodes of your Tangle can be achieved. The IOTA Foundation intends to provide automatic, "one click" deployment of this kind of enhanced architectures in a future version of this software.
To support the deployment of an IOTA Tangle, the IOTA Community has developed a set of shell scripts and configuration templates to make it easier to deploy a (Docker based) Tangle with the architecture described above. You can also customize the default configuration files if, for instance, you want to enable extra Hornet plugins.
Behind the scenes, the process will launch all the Docker containers (through docker-compose), create a key pair for the Coordinator, configure the Coordinator public key for the initial node, generate an initial IOTA Address holding all IOTAs, the identity for our Nodes, etc i.e. our deployment architecture and all the steps described here, but fully automated, with "one click"!.
The Parameters of this "one click" installation are as follows (further details can be found at here:
- One Private Key for signing milestones and just one milestone signer (the Coordinator)
- Coordinator Milestones Period:
60seconds, check this line of code
- Spammer Settings, check these lines of code.
Further instructions for AWS deployments can be found here. If you want to know lower-level details of the AWS installation, how to do it yourself in any Docker-enabled VM, and what happens under the scenes, please continue reading.
You need Docker and Docker Compose. Docker Compose is a tool for defining and running multi-container Docker applications. Yaml files are used to configure the required services. This means all container services can be brought up in a single command. Docker Compose is installed by default as part of Docker for Windows and Docker for Mac, however Linux users will need to follow the instructions found here
You can check your current Docker and Docker Compose versions using the following commands:
docker-compose -vdocker version
Please ensure that you are using Docker version
18.03 or higher and Docker Compose
1.21 or higher and upgrade if
To start with, you need to clone the one-click-tangle repository as follows:
git clone https://github.com/iotaledger/one-click-tanglecd one-click-tangle
Then, ensure that the
private-tangle.sh script has execution permissions:
cd one-click-tangle/hornet-private-netchmod +x ./private-tangle.sh
To start our Tangle through the command line:
You can optionally pass the amount of time (in seconds) to wait for the Coordinator bootstrap step. This step enables the Coordinator to bootstrap by emitting its first milestone.
Behind the scenes, our process will create the identity for the Coordinator, the keys that will be used for signing milestones, an initial IOTA Address holding all IOTAs, the identity of our Nodes, etc i.e. all the steps described here, but fully automated.
After the process finishes you should see the following docker containers up and running:
docker ps -a
8474fd9ced97 gohornet/hornet:latest "/app/hornet" 29 hours ago Up 29 hours 8081/tcp, 14265/tcp, 15600/tcp, 14626/udp spammer 8804bfd795ec gohornet/hornet:latest "/app/hornet" 2 days ago Up 2 days 0.0.0.0:8081->8081/tcp, 0.0.0.0:14265->14265/tcp, 1883/tcp, 0.0.0.0:15600->15600/tcp, 14626/udp node196b2047a6ebe gohornet/hornet:latest "/app/hornet" 2 days ago Up 2 days 8081/tcp, 14265/tcp, 15600/tcp, 14626/udp cood527976593c5 gohornet/hornet:latest "/app/hornet" 8 hours ago Up 8 hours 1883/tcp, 8081/tcp, 14265/tcp, 15600/tcp, 0.0.0.0:14626->14626/udp node-autopeering
Alternatively, the following files should have been created for you:
The P2P identities that can be used to peer these Nodes with other Nodes:
coo.identity.txt. The P2P identity of the Coordinator.
node1.identity.txt. The P2P identity of the node1.
spammer.identity.txt. The P2P identity of the Spammer.
node-autopeering.identity.txt. The P2P identity of the autopeering Entry Node.
The address that holds all the IOTAs and its corresponding keys:
key-pair.txt. The Ed25519 Key pair corresponding to the address that holds all the IOTAs.
address.txt. The address that holds all IOTAs initially.
The Coordinator's cryptographic materials:
coo-milestones-key-pair.txt. The Ed25519 key pair used by the Coordinator to sign milestones. Keep it safe!
coo-milestones-public-key.txt. The Ed25519 public key that can be used to verify Coordinator's milestones.
The initial snapshot for your Tangle:
snapshots/private-tangle/full_snapshot.bin. It contains just one IOTA address that is holding all IOTAs.
If you browse to
http://localhost:8081 you can test out the Hornet Dashboard.
You can find the database files of your Tangle at
When a snapshot is created,
1000000000 tokens are sent to the treasury.
2779529283277761 out of the total number of tokens, which is
2779530283277761 are sent to the mint address. To change the amount that is allocated to the treasury, you can change the value
The total amount of tokens allocated to the treasury should not be equal to the total supply of tokens which is
2779530283277761. Otherwise the mint address will have zero tokens.
You operate your Tangle by issuing one of the following commands:
Once we have your Tangle up and running, you can install and run a Tangle Explorer as follows:
cd ../explorer./tangle-explorer.sh install ../hornet-private-net
The Tangle Explorer will automatically be configured with the parameters of your Tangle and once the docker build process finishes, you should find the following additional docker containers up and running:
dd4bcad67c5e iotaledger/explorer-webapp "docker-entrypoint.s…" 2 days ago Up 2 days 0.0.0.0:8082->80/tcp explorer-webapp7c22023f4316 iotaledger/explorer-api "docker-entrypoint.s…" 2 days ago Up 2 days 0.0.0.0:4000->4000/tcp explorer-api
You can now get access to your Tangle Explorer through
For convenience reasons, a script is also available to add new Nodes to an already running Tangle.
To do so, you can follow these steps:
cd ./extra-nodeschmod +x ./private-hornet.sh./private-hornet.sh install "my-node:14266:15601:8082"
The main parameter is a Node connection string. Such string has different fields separated by a colon (
:). The first field is the (container and host) name of your Node and, at installation time, it can be followed, optionally, by the TCP port numbers corresponding to the API endpoint, the peering endpoint and the dashboard endpoint.
If no port numbers are provided, i.e. only the container name is supplied, no ports will be exposed to the host. In addition, you can omit some of the ports, but the separator
: has to be kept, for instance, if you just only want to expose the dashboard port to the host you can run:
./private-hornet.sh install "my-node:::8082"
After executing the commands described above, a new Docker container (named
my-node) executing a Hornet node will be running. This Hornet node will be automatically peered. The snapshot, Coordinator's public keys, and autopeering entry node address will be taken from the snapshot and configuration folders of your Tangle.
Note: In case you want to spin a node from a different machine (or base folder) you would need to manually pass those parameters including a multiaddr peer address of a node to peer with (for instance
node1) you want to peer with, as explained here.
Mac OS users should install GNU sed, for instance, using
brew install --default-names gnu-sed.
There could be limitations in the number of peers triggered by the maximum number of unknown peers parameter. To overcome it, you may need to change this configuration property
Try using one of the client libraries to send transactions to the nodes in your Tangle.