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. 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. 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. 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:

Parameter Meaning
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. Docker

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: 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 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 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 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 \

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. Manually

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. Automated

5.4. Description

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). Overlay network can be created if your instance is part of a Swarm cluster. Another method does not involve creating a Swarm cluster but requires a distributed key-value storage. There is a guide on how to create such overlay network.

This method is also suitable for local-only deployments and does not require any key-value storage.

5.5. Requirements

Tested on Ubuntu 16.04, 18.04
  • Local:

    • python3, python3-dev
    • PIP modules: ansible(>=2.4), future, sha3(for Python<3.6)
  • Remote:

    • Docker (>=17.12)
    • python3
    • 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 iroha-docker playbook.


docker.io package from Ubuntu repos will not work. Either use Ansible role or install Docker following official instructions for your OS flavor.

5.6. Quick Start

  1. Install Ansible .. code-block:: guess

    pip3 install ansible

  2. Create inventory list containing IP address of the remote host


    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_portiroha_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 (playbooks/iroha-docker/main.yml)


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.

5.7. Initial configuration

See defaults/main.yml file to get more details about available configuration options.

5.8. Examples

Example 1 Deploying 6 Iroha peers on two remote hosts communicating using public IP addresses. With 2 and 4 replicas on each host respectively.

  1. 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


    Put this file into ``../../inventory/`` directory.
  2. 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 sudo without prompting for a password. Set -u option for ansible-playbook command.

  3. Create two YAML files in ../playbooks/iroha-docker/host_vars directory:

       iroha_replicas: 2
    iroha_replicas: 4
  4. 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.



If /usr/bin/python does 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/python3 is not symlinked to /usr/bin/python which Ansible expects to find. The problem can be solved by setting ansible_python_interpreter variable to /usr/bin/python3.

5.8.1. Dealing with troubles

—”Please, help me, because I…” Do not have Iroha daemon binary

You can build Iroha daemon binary from sources. You can get binaries here Do not have a config file

Check how to create a configuration file by following this link Do not have a genesis block

Create genesis block by generating it via iroha-cli or manually, using the example and checking out permissions 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