Hyperledger Aries ACA-Py Agents Setup and Running Tutorials — Part III— Dev Environment Setup

Introduction

In Part I, I’ve introduced the general benefits of using SSI and why Hyperledger Indy and Aries can fit in the big picture. In Part II, a scenario overview and tools were described. This Part III will show details on how to set up a Dev environment to run an ACA-Py agent V0.6.0.

Azure Environment Setup

As stated in Part II, I’ve mainly used the Azure environment to set up two VMs to run ACA-Py agents. This section will not show the details of how to set up a VM in Azure, as there are a bunch of online tutorials such as official Azure docs that can show you the details of how to make it. I only show the key configs I’ve used for running ACA-Py agents.

1. VM OS: Ubuntu 18.04-LTS with a public IP.

2. Network Inbound rules:

(1) Port 22: make sure you can SSH to your VM from you local machine

(2) Port 9000: make sure you can access the ledger browser of a local Von development network

(3) Port 6543: used for the von network to connect to the indy tail file server

(4) Two self defined Port numbers (e.g. 8000 and 8001): {self-defined port I} is used for agent-level connection, and {self-defined port II} is used for accessing an ACA-Py agent built-in Open REST APIs. Make sure the two ports can be accessed by your local machine and the other VM assuming you would run another ACA-Py agent on the other VM as how I do.

Tools Preparation in the VM

Once sshing into the VM, install Docker and Docker compose in the VM. Again, there are many online tutorials available. Below are the version I’ve used.

Docker version: 20.10.3, build 48d30b5. For installation tutorials, see this doc.

Docker-compose version: 1.28.4, build cabd5cfb. For installation tutorials, see this doc.

Git is also needed and should be available by default in the VM if you use the same version as mine. If it is not available in the VM, also install it manually. Below is the version I’ve used for Git.

Git: version 2.17.1

Install a Local Dev Von-network on the VM

Clone the Von-network repo by running the below git command

git clone https://github.com/bcgov/von-network.git

then run the below command to run a local von development network. Behind the scene, it uses a docker-compose file to quickly spin up a 4-nodes Indy network + the ledger web browser.

./von-network/mange up

If successful, you should see something similar as shown in figure 1. It shows 5 containers are up and running.

figure 1 — Run a local dev von-network in docker containers

Then, if you open your browser and access the URL: {your VM’s public IP}:9000, you should be able to see the ledger browser as shown in figure 2. If you can’t access it, please check if you have whitelisted the port 9000 in your network inbound rules.

figure 2 — the ledger browser when the local von network is up and running

Install a Local Dev Tails File Server on the VM

Once the von dev network is up and running in the VM, run the below command to clone the indy tails server.

git clone https://github.com/bcgov/indy-tails-server.git

Then run below command to run the local indy tails server (for credential revocation purpose) in 2 containers.

./indy-tails-server/docker/manage up

Once successful, you should see something like figure 3.

figure 3 — indy tails server is up and running in docker containers

The Indy tails server container will auto create a ngrok url for public access. Run the below command to get the public ngrok url

docker logs docker_ngrok-tails-server_1

if successful, you should some a few lines printed out. the very last part of the last line should be something like “url=https://{random code}.ngrok.io” with an ngrok url. Copy and paste it somewhere, because we will need it when running the ACA-Py agent.

Run An ACA-Py Agent as An Issuer/Verifier on the VM

Once the local dev von network and local dev tails file server are up and running, we can eventually run an ACA-Py agent in the VM now. Before running the ACA-Py agent, you might still want double check if the two pieces are up and running properly. Run the below command to see if you have 7 containers up and running.

docker ps

If you see 7 containers as shown in figure 4, it means your local environment in this VM is ready.

figure 4 — checking all 7 containers are up and running before running an ACA-Py agent

In this case, we will be running the first ACA-Py agent as an issuer/verifier. As an issuer requires a public DID to be registered on the Indy network, we have to generate one for our issuer agent. We can use the ledger browser as shown in figure 2 to make this happen. Use the default option — “Register from seed” in the “Authenticate a New DID” section in the ledger browser, and put “issuer00000000000000000000000000” as the value in the “wallet seed” field, remain the role as the default — Endorser and click on the “Register DID” button. Once successful, you should see information like “Identity successfully registered” + detailed information such as Seed, DID and Verkey to be shown right below the “Register DID” button (see figure 5).

figure 5 — successfully registered a public DID for an issuer agent

Run below command to clone the ACA-Py repo to the VM.

git clone https://github.com/hyperledger/aries-cloudagent-python.git

Run below command to a particular folder.

cd ./aries-cloudagent-python/scripts

Run below command to use the V0.6.0 of ACA-Py.

git checkout tags/0.6.0

The below long command is used to run the ACA-Py agent V0.6.0 in a docker container.

PORTS="{Self-defined Port I} {Self-defined Port II}" \ 
./run_docker start \
-l Issuer \
-it http 0.0.0.0 {Self-defined Port I} \
-ot http \ 
--admin 0.0.0.0 {Self-defined Port II} \
--admin-insecure-mode \
-e http://{Your VM's public IP}:{Self-defined port I} \
--genesis-url http:// {Your VM's public IP}:9000/genesis \
--wallet-type indy \
--wallet-name issuerwallet \
--wallet-key issuerkey \
--log-level ‘info’ \
--auto-provision \
--auto-accept-invites \
--auto-accept-requests \
--auto-ping-connection \
--tails-server-base-url  {Ngrok URL of the tails file server} \
--seed issuer00000000000000000000000000

There are parameters that need to be replaced as the real values. The parameters are:

{Self-defined Port I}: this port is used for an ACA-Py agent to communicate with other ACA-Py agents.

{Self-defined Port II}: this port is used as the admin port for an ACA-Py agent, so we can find the REST APIs by accessing the ACA-Py agent via this port.

{Your VM’s public IP}: this is the VM’s public IP that runs an ACA-Py agent.

{Ngrok URL of the tails file server}: this is an ngrok URL auto generated when the tails file server is running on the VM.

If we replace these parameters with some fake values for demo purposes, it looks like the one as shown below:

{Self-defined Port I}: 8000

{Self-defined Port II}:8001

{Your VM’s public IP}: 90.0.0.0

{Ngrok URL of the tails file server}: https://123456789012.ngrok.io

The command would look like below:

PORTS="8000 8001" \ 
./run_docker start \
-l Issuer \
-it http 0.0.0.0 8000 \
-ot http \ 
--admin 0.0.0.0 8001 \
--admin-insecure-mode \
-e http://90.0.0.0:8000 \
--genesis-url http://90.0.0.0:9000/genesis \
--wallet-type indy \
--wallet-name issuerwallet \
--wallet-key issuerkey \
--log-level ‘info’ \
--auto-provision \
--auto-accept-invites \
--auto-accept-requests \
--auto-ping-connection \
--tails-server-base-url https://123456789012.ngrok.io \
--seed issuer00000000000000000000000000

Here, quickly explain the long command.

1. “run_docker” is a built-in command sitting in the “scripts” directory of the “aries-cloudagent-python” repo. By putting “start” after it, it runs ACA-Py as a docker container to trigger the ACA-Py to run properly. To see all options for this command, simply type in the below command, and you will see all the options for this command.

./run_docker start --help

2.-l issuer, the name/label of the agent. In our case, it’s issuer.

3.-it http 0.0.0.0 {self-defined port I}, define the port number (in my case, I use 8000) of receiving inbound message from other agents.

4.-ot http, define the out bound transports protocol, which is http. Web socket is also supported, if we put a value “ws”.

5.--admin 0.0.0.0 {self-defined port II}, defines the port number for accessing the built-in Open REST APIs for ACA-Py agent. In my case, I use 8001.

6.--admin-insecure-mode, allows us to access the Open REST APIs web page without providing any keys. Only used for dev purpose.

7.-e http://{VM’s public IP}:{self-defined port I}, the help info shows “Specifies the endpoints to put into DIDDocs to inform other agents of where they should send messages destined for this agent”.

8.--genesis-url http:// {Your VM’s public IP}:9000/genesis, the help info shows “Specifies the url from which to download the genesis transactions”.

9.--wallet-type indy, use the “indy” mode for wallet (i.e. storage that will store all the useful information such as private DIDs, credentials). This auto uses the SQLite DB for storage.

10.--wallet-name issuerwallet, the help info shows “Specifies the wallet name to be used by the agent”.

11.--wallet-key issuerkey, the help info shows “Specifies the master key value to use to open the wallet”.

12.--log-level ‘info’, show helpful log information.

13.--auto-provision, the help info shows “ If the requested profile does not exist, initialize it with the given parameters.”, but not very clear on what the “profile” means.

14.--auto-accept-invites, very useful one that simplifies the one-time connection establishment between agents. The help info shows “Automatically accept invites without firing a webhook event or waiting for an admin request”.

15.--auto-accept-requests, very useful one that simplifies the one-time connection establishment between agents. The help info shows “Automatically accept connection requests without firing a webhook event or waiting for an admin request”.

16.--auto-ping-connection, very useful one, it auto sends a ping message to the other agent to verify the connection channel has been established.

17.--tails-server-base-url, the ngrok url of the tails file server mentioned earlier to enable the credential revocation to work.

18.--seed issuer00000000000000000000000000, the help info shows “Specifies the seed to use for the creation of a public DID for the agent to use with a Hyperledger Indy ledger, or a local (‘ — wallet-local-did’) DID. If public, the DID must already exist on the ledger”.

If successful, you should eventually see information as shown in figure 6. In figure 6, you can also tell the same public DID is retrieved by the issuer agent, and {self-defined Port I} is used in the Inbound Transports url (in my case, it’s 8000) and {self-defined Port II} is used in the “Administration API” (in my case, it’s 8001).

figure 6 — successfully run an ACA-Py agent V0.6.0 as an issuer

Now, you can also access the URL: {Your VM’s public IP}:8001, and if successful, you will see a long list of built-in Open APIs defined for the ACA-Py agent (see figure 7).

figure 7 — Open APIs for the issuer agent in the browser

Run The Second ACA-Py Agent as An Holder on the VM

Basically, the above process remains the nearly the same, but doesn’t require a public DID to be generated.

Conclusion

Hopefully, by following all the steps in this Part III, readers should be able to run two ACA-Py agents V0.6.0 on two Azure VMs. In Part IV, I’ll cover how to establish the one-time communication channel between two agents. See you soon.