Working with Iroha Binaries

Working with Iroha involves several different binaries (e.g., iroha). This is a reference of available binaries, and the methods of their installation.

Iroha 2 provides the following binary executables:

• irohad — the main Iroha CLI that is used to start a peer daemon.

• iroha — Iroha Client CLI that is used to interact with an Iroha peer.

• kagami — a tool that is used to generate and validate various types of data (e.g., cryptographic keys, genesis blocks, default client and peer configuration files).

  See also:

  • Generating Cryptographic Keys — instructions on how to generate cryptographic keys with kagami.
  • Configure Iroha > Genesis Block: Generation — instructions on how to generate a default genesis block with kagami.
  • Configure Iroha > Peer Configuration: Generation — instructions on how to generate a default peer configuration file with kagami.
  • Configure Iroha > Client Configuration: Generation — instructions on how to generate a default client configuration file with kagami.

There are two main ways to work with Iroha 2 binaries:

• Using the source GitHub repository:
  • Installing from the GitHub source repository.
  • Running from a cloned GitHub repository.
• Using the pre-built Docker images.

Using the Source GitHub Repository

To perform any of the actions using the GitHub repository (i.e., building & installing, or running binaries), first install the Rust toolchain.

Installing from the GitHub Source Repository

You can install Iroha 2 binaries system-wide with the Rust cargo tool:

irohad

cargo install --git https://github.com/hyperledger-iroha/iroha.git irohad --locked
irohad --help

iroha

cargo install --git https://github.com/hyperledger-iroha/iroha.git iroha_cli --locked
iroha --help

kagami

cargo install --git https://github.com/hyperledger-iroha/iroha.git iroha_kagami --locked
kagami --help

TIP

For more details on cargo install and its [options], see The Cargo Book > cargo-install(1).

Running from a Cloned GitHub Repository

You may want to run the binaries without installing them system-wide. This will involve cloning Iroha's source code and using cargo run.

First, clone the hyperledger-iroha/iroha GitHub repository:

git clone https://github.com/hyperledger-iroha/iroha.git <clone-folder>
cd <clone-folder>

To run an Iroha 2 binary with cargo install, execute one of the following commands in your terminal:

irohad

cargo run --release --bin irohad -- --help

iroha

cargo run --release --bin iroha -- --help

kagami

cargo run --release --bin kagami -- --help

TIP

For more details on cargo run and its [options], see The Cargo Book > cargo-run(1).

Using the Pre-Built Docker Images

First, install Docker.

Then, to install a binary from a pre-built Docker image, execute one of the following commands:

iroha

docker run -t hyperledger/iroha:dev iroha

kagami

docker run -t hyperledger/iroha:dev kagami

For most tasks iroha binary requires:

• a config file that needs to be mapped to the container
• access to the host machine's network connection

Below is an example of how to launch iroha with a your custom config and network access.

docker run --network host -v /path/to/host/config:/config -t hyperledger/iroha:dev iroha --config /config/custom-client-config.toml

where:

custom-client-config.toml - is the name of your customs config file

/path/to/host/config - is the location of your custom config on your host machine

TIP

irohad should be started using docker compose. Please refer to the sample configuration in the Iroha 2 repository.