5.3. Deploying Iroha¶
Hyperledger Iroha can be deployed in different ways, depending on the perspective and the purpose. There can be either a single node deployed, or multiple nodes running in several containers on a local machine or spread across the network — so pick any case you need. This page describes different scenarios and is intended to act as a how-to guide for users, primarily trying out Iroha for the first time.
5.3.1. Running single instance¶
Generally, people want to run Iroha locally in order to try out the API and explore the capabilities. This can be done in local or container environment (Docker). We will explore both possible cases, but in order to simplify peer components deployment, it is advised to have Docker installed on your machine.
18.104.22.168. Local environment¶
By local environment, it is meant to have daemon process and Postgres deployed without any containers. This might be helpful in cases when messing up with Docker is not preferred — generally a quick exploration of the features.
22.214.171.124.1. Run postgres server¶
In order to run postgres server locally, you should check postgres website and follow their description. Generally, postgres server runs automatically when the system starts, but this should be checked in the configuration of the system.
126.96.36.199.2. Run iroha daemon (irohad)¶
There is a list of preconditions which you should meet before proceeding:
- Postgres server is up and running
- irohad Iroha daemon binary is built and accessible in your system
- The genesis block and configuration files were created
- Config file uses valid postgres connection settings
- A keypair for the peer is generated
- This is the first time you run the Iroha on this peer and you want to create new chain
Have you got something that is not the same as in the list of assumptions? Please, refer to the section below the document, titled as Dealing with troubles.
In case of valid assumptions, the only thing that remains is to launch the daemon process with following parameters:
|config||configuration file, containing postgres connection and values to tune the system|
|genesis_block||initial block in the ledger|
|keypair_name||private and public key file names without file extension, used by peer to sign the blocks|
Specifying a new genesis block using –genesis_block with blocks already present in ledger requires –overwrite_ledger flag to be set. The daemon will fail otherwise.
An example of shell command, running Iroha daemon is
irohad --config example/config.sample --genesis_block example/genesis.block --keypair_name example/node0
If you have stopped the daemon and want to use existing chain — you should not pass the genesis block parameter.
In order to run Iroha peer as a single instance in Docker, you should pull the image for Iroha first:
docker pull hyperledger/iroha:latest
Use latest tag for latest stable release, and develop for latest development version
Then, you have to create an enviroment for the image to run without problems:
188.8.131.52.1. Create docker network¶
Containers for Postgres and Iroha should run in the same virtual network, in order to be available to each other. Create a network, by typing following command (you can use any name for the network, but in the example, we use iroha-network name):
docker network create iroha-network
184.108.40.206.2. Run Postgresql in a container¶
Similarly, run postgres server, attaching it to the network you have created before, and exposing ports for communication:
docker run --name some-postgres \ -e POSTGRES_USER=postgres \ -e POSTGRES_PASSWORD=mysecretpassword \ -p 5432:5432 \ --network=iroha-network \ -d postgres:9.5
220.127.116.11.3. Create volume for block storage¶
Before we run iroha daemon in the container, we should create persistent volume to store files, storing blocks for the chain. It is done via the following command:
docker volume create blockstore
18.104.22.168.4. Running iroha daemon in docker container¶
- There is a list of assumptions which you should review before proceeding:
- Postgres server is running on the same docker network
- There is a folder, containing config file and keypair for a single node
- This is the first time you run the Iroha on this peer and you want to create new chain
If they are met, you can move forward with the following command:
docker run --name iroha \ # External port -p 50051:50051 \ # Folder with configuration files -v ~/Developer/iroha/example:/opt/iroha_data \ # Blockstore volume -v blockstore:/tmp/block_store \ # Postgres settings -e POSTGRES_HOST='some-postgres' \ -e POSTGRES_PORT='5432' \ -e POSTGRES_PASSWORD='mysecretpassword' \ -e POSTGRES_USER='postgres' \ # Node keypair name -e KEY='node0' \ # Docker network name --network=iroha-network \ hyperledger/iroha:latest
5.3.2. Running multiple instances (peer network)¶
In order to set up a peer network, one should follow routines, described in this section. In this version, we support manual deployment and automated by Ansible Playbook. Choose an option, that meets your security criteria and other needs.
By manual deployment, we mean that Iroha peer network is set up without automated assistance. It is similar to the process of running a single local instance, although the difference is the genesis block includes more than a single peer. In order to form a block, which includes more than a single peer, or requires customization for your needs, please take a look at Dealing with troubles section.
This role deploys multiple replicas of Iroha containers (one Iroha peer per container) on remote hosts. Each Iroha peer can communicate with others in two ways:
- using public IP addresses or hostnames set in inventory list OR
- using private IP addresses of the Docker overlay network
The first one is easier to implement since it does not require preliminary configuration of the remote hosts. Just make sure that network ports are not firewalled. You can check the port list in the generated Docker Compose file (
docker-compose.yml) after deployment.
This option is enabled by default.
The second one can be used when there exists an overlay network between the hosts. In short, overlay network allows for Docker containers to communicate using a single subnet. Such that each container would have a unique IP address in that subnet. Learn more in official Docker documentation (https://docs.docker.com/network/overlay). We recommend to use Calico for setting up Docker overlay network since it can be used as a network plugin (https://docs.projectcalico.org/v1.5/getting-started/docker/tutorials/basic).
The second way is also suitable for local-only deployments.
Tested on Ubuntu 16.04, 18.04
- python3, python3-dev
- PIP modules: ansible(>=2.4), future, sha3(for Python<3.6)
- Docker (>=17.12)
- PIP modules: docker, docker-compose
There is a role for setting up a remote part of the dependencies named
docker. It works for Ubuntu OS only. Check
docker.iopackage from Ubuntu repos will not work. Either use Ansible role or install Docker following official instructions for your OS flavor.
22.214.171.124.3. Quick Start¶
Install Ansible .. code-block:: guess
pip3 install ansible
Create inventory list containing IP address of the remote host
[all] 192.168.122.109 Put this file into ``../../inventory/`` directory.
cd ../../ && ansible-playbook -b -e 'ansible_ssh_user=ubuntu' -i inventory/iroha.list playbooks/iroha-docker/main.yml
This will deploy 6 Iroha Docker containers along with 6 Postgres containers on the remote host specified in
iroha.list file. Remote user is
ubuntu. Torii port of each container is exposed on the host. Iroha peer can be communicated over port defined in
iroha_torii_port variable (50051 by default). Overall, each host will listen the following port range:
iroha_torii_port + number-of-containers - 1.
It will also install Docker along with required python modules. If you want to skip this step, comment out
docker role in the playbook (
This command escalates privileges on a remote host during the run. It is required to be able to spin up Docker containers. We recommend to run the playbook using a passwordless remote sudo user.
126.96.36.199.4. Initial configuration¶
defaults/main.yml file to get more details about available configuration options.
Example 1 Deploying 6 Iroha peers on two remote hosts communicating using public IP addresses. With 2 and 4 replicas on each host respectively.
Create inventory list containing IP addresses (or hostnames if they are mutually resolve-able on both hosts) of two hosts that will run Iroha peers
[all] 192.168.122.109 192.168.122.30 Put this file into ``../../inventory/`` directory.
Make sure you can SSH with a root account into either of these hosts using a private key.
You can also SSH with the user other than root. Make sure it can execute
sudowithout prompting for a password. Set
Create two YAML files in
replicas: 2 **192.168.122.30.yml**
Run the playbook
ansible-playbook -i inventory/iroha.list -b playbooks/iroha-docker/main.yml
Example 2 Deploying 6 Iroha peers on two remote hosts communicating over overlay network (Calico) using custom hostnames.
/usr/bin/pythondoes not exist on a remote host, Ansible will fail with the misleading message:
... Make sure this host can be reached over ssh. This usually happens when Ansible uses Python 3. On Ubuntu systems
/usr/bin/python3is not symlinked to
/usr/bin/pythonwhich Ansible expects to find. The problem can be solved by setting
5.3.3. Dealing with troubles¶
—”Please, help me, because I…”
188.8.131.52. Do not have Iroha daemon binary¶
You can build Iroha daemon binary from sources. You can get binaries here
184.108.40.206. Do not have a genesis block¶
220.127.116.11. Do not have a keypair for a peer¶
In order to create a keypair for an account or a peer, use iroha-cli binary by passing the name of the peer with –new_account option. For example:
./iroha-cli --account_name newuser@test --new_account