There are two ways to run the alice/faber demo with endorser support enabled.
## Run Faber as an Author, with a dedicated Endorser agent
This approach runs Faber as an un-privileged agent, and starts a dedicated Endorser sub-process to endorse Faber's transactions.
This approach runs Faber as an un-privileged agent, and starts a dedicated Endorser Agent in a sub-process (an instance of ACA-Py) to endorse Faber's transactions.
Start a VON Network instance and a Tails server:
Start a VON Network and a Tails server.
- Following the [Building and Starting](https://github.com/bcgov/von-network/blob/main/docs/UsingVONNetwork.md#building-and-starting) section of the VON Network Tutorial to get ledger started. You can leave off the `--logs` option if you want to use the same terminal for running both VON Network and the Tails server. When you are finished with VON Network, follow the [Stopping And Removing a VON Network](https://github.com/bcgov/von-network/blob/main/docs/UsingVONNetwork.md#stopping-and-removing-a-von-network) instructions.
- Run an AnonCreds revocation registry tails server in order to support revocation by following the instructions in the [Alice gets a Phone](https://github.com/hyperledger/aries-cloudagent-python/blob/master/demo/AliceGetsAPhone.md#run-an-instance-of-indy-tails-server) demo.
Start up Faber as Author (note the tails file size override, to allow testing of the revocation registry roll-over):
...
...
@@ -15,7 +17,7 @@ Start up Faber as Author (note the tails file size override, to allow testing of
The IIWBook demo is a real (play) self-sovereign identity demonstration. During the demo, you will get a mobile agent (sorry - IOS only right now), and use that agent to connect with several enterprise services to collect and prove credentials. The two services in the demo (the [email verification service](https://github.com/bcgov/indy-email-verification) and [IIWBook](https://github.com/bcgov/iiwbook)) are both instances of ACA-Py, and all the agents are using DIDComm to communicate. Learn about and run the demo at [https://vonx.io/how_to/iiwbook](https://vonx.io/how_to/iiwbook). Developers, when you are ready, check out the code in the repos of the two services to see how they implement Django web server-based controller and agent.
## The Alice/Faber Python demo
The Alice/Faber demo is the (in)famous first verifiable credentials demo. Alice, a former student of Faber College ("Knowledge is Good"), connects with the College, is issued a credential about her degree and then is asked by the College for a proof. There are a variety of ways of running the demo. The easiest is in your browser using a site ("Play with VON") that let's you run docker containers without installing anything. Alternatively, you can run locally on docker (our recommendation), or using python on your local machine. Each approach is covered below.
...
...
@@ -63,19 +59,20 @@ Jump to the [Follow the Script](#follow-the-script) section below for further in
### Running in Docker
Running the demo in docker requires having a `von-network` (a Hyperledger Indy public ledger sandbox) instance running in docker locally. See the [Running the Network Locally](https://github.com/bcgov/von-network#running-the-network-locally) section of the `von-network` readme file for more info.
Running the demo in docker requires having a `von-network` (a Hyperledger Indy public ledger sandbox) instance running in docker locally. See the [VON Network Tutorial](https://github.com/bcgov/von-network/blob/main/docs/UsingVONNetwork.md) for guidance
on starting and stopping your own local Hyperledger Indy instance.
Open three `bash` shells. For Windows users, `git-bash` is highly recommended. bash is the default shell in Linux and Mac terminal sessions.
In the first terminal window, start `von-network` by following the [Running the Network Locally](https://github.com/bcgov/von-network#running-the-network-locally) instructions.
In the first terminal window, start `von-network` by following the [Building and Starting](https://github.com/bcgov/von-network/blob/main/docs/UsingVONNetwork.md#building-and-starting) instructions.
In the second terminal, change directory into `demo` directory of your clone of this repository. Start the `faber` agent by issuing the following command:
In the second terminal, change directory into `demo` directory of your clone of the Aries Cloud Agent Python repository. Start the `faber` agent by issuing the following command:
``` bash
./run_demo faber
```
In the third terminal, change directory into `demo` directory of your clone of this repository. Start the `alice` agent by issuing the following command:
In the third terminal, change directory into `demo` directory of your clone of the Aries Cloud Agent Python repository. Start the `alice` agent by issuing the following command:
``` bash
./run_demo alice
...
...
@@ -87,6 +84,8 @@ Jump to the [Follow the Script](#follow-the-script) section below for further in
The following is an approach to to running the Alice and Faber demo using Python3 running on a bare machine. There are other ways to run the components, but this covers the general approach.
We don't recommend this approach if you are just trying this demo, as you will likely run into issues with the specific setup of your machine.
#### Installing Prerequisites
We assume you have a running Python 3 environment. To install the prerequisites specific to running the agent/controller examples in your Python environment, run the following command from this repo's `demo` folder. The precise command to run may vary based on your Python environment setup.
While that process will include the installation of the Indy python prerequisite, you still have to build and install the `libindy` code for your platform. Follow the [installation instructions](https://github.com/hyperledger/indy-sdk#installing-the-sdk) in the indy-sdk repo for your platform.
#### Start a local indy ledger
#### Start a local Indy ledger
Use instructions in the [indy-sdk repo](https://github.com/hyperledger/indy-sdk#how-to-start-local-nodes-pool-with-docker) to run a local ledger.
Start a local `von-network` Hyperledger Indy network running in Docker by following the VON Network [Building and Starting](https://github.com/bcgov/von-network/blob/main/docs/UsingVONNetwork.md#building-and-starting) instructions.
We strongly recommend you use Docker for the local Indy network until you really, really need to know the details of running an Indy Node instance on a bare machine.
#### Genesis File handling
> Assuming you followed our advice and are using a VON Network instance of Hyperledger Indy, you can ignore this section. If you started the Indy ledger **without** using VON Network, this information might be helpful.
An Aries agent (or other client) connecting to an Indy ledger must know the contents of the `genesis` file for the ledger. The genesis file lets the agent/client know the IP addresses of the initial nodes of the ledger, and the agent/client sends ledger requests to those IP addresses. When using the `indy-sdk` ledger, look for the instructions in that repo for how to find/update the ledger genesis file, and note the path to that file on your local system.
The envrionment variable `GENESIS_FILE` is used to let the Aries demo agents know the location of the genesis file. Use the path to that file as value of the `GENESIS_FILE` environment variable in the instructions below. You might want to copy that file to be local to the demo so the path is shorter.
If you want to be able to browse your local ledger as you run the demo, clone the [von-network](https://github.com/bcgov/von-network) repo, go into the root of the cloned instance and run the following command, replacing the `/path/to/local-genesis.txt` with a path to the same genesis file as was used in starting the ledger.
If you followed our advice and are using a VON Network instance of Hyperledger Indy, you can ignore this section, as you already have a Ledger browser running, accessible on http://localhost:9000.
If you started the Indy ledger **without** using VON Network, and you want to be able to browse your local ledger as you run the demo, clone the [von-network](https://github.com/bcgov/von-network) repo, go into the root of the cloned instance and run the following command, replacing the `/path/to/local-genesis.txt` with a path to the same genesis file as was used in starting the ledger.
With the rest of the pieces running, you can run the Alice and Faber controllers and agents. To do so, `cd` into the `demo` folder your clone of this repo in two terminal windows and run the following, replacing the `/path/to/local-genesis.txt`.
With the rest of the pieces running, you can run the Alice and Faber controllers and agents. To do so, `cd` into the `demo` folder your clone of this repo in two terminal windows.
If you are using a VON Network instance of Hyperledger, run the following commands:
If you started the Indy ledger **without** using VON Network, use the following commands, replacing the `/path/to/local-genesis.txt` with the one for your configuration.
Note that Alice and Faber will each use 5 ports, e.g. using the parameter `... --port 8020` actually uses ports 8020 through 8024. Feel free to use different ports if you want.
Note that Alice and Faber will each use 5 ports, e.g., using the parameter `... --port 8020` actually uses ports 8020 through 8024. Feel free to use different ports if you want.
Everything running? See the [Follow the Script](#follow-the-script) section below for further instructions.
...
...
@@ -201,7 +218,7 @@ To enable support for revoking credentials, run the `faber` demo with the `--rev
Note that you don't specify this option with `alice` because it's only applicable for the credential `issuer` (who has to enable revocation when creating a credential definition, and explicitely revoke credentials as appropriate; alice doesn't have to do anything special when revocation is enabled).
You need to run a revocation registry in order to support revocation - the details are described in the [Alice gets a Phone](https://github.com/hyperledger/aries-cloudagent-python/blob/master/demo/AliceGetsAPhone.md#run-an-instance-of-indy-tails-server) demo instructions.
You need to run an AnonCreds revocation registry tails server in order to support revocation - the details are described in the [Alice gets a Phone](https://github.com/hyperledger/aries-cloudagent-python/blob/master/demo/AliceGetsAPhone.md#run-an-instance-of-indy-tails-server) demo instructions.
Faber will setup support for revocation automatically, and you will see an extra option in faber's menu to revoke a credential:
...
...
@@ -249,7 +266,7 @@ This is described in [Endorser.md](Endorser.md)
### Run Indy-SDK Backend
This runs using the indy-sdk libraries instead of askar:
This runs using the older (and not recommended) indy-sdk libraries instead of [Aries Askar](:uhttps://github.com/hyperledger/aries-ask):
```bash
./run_demo faber --wallet-type indy
...
...
@@ -263,27 +280,27 @@ To enable mediation, run the `alice` or `faber` demo with the `--mediation` opti
./run_demo faber --mediation
```
This will start up a second "mediator" agent and automatically set the alice/faber connection to use the mediator.
This will start up a "mediator" agent with Alice or Faber and automatically set the alice/faber connection to use the mediator.
### Multi-tenancy
### Multi-ledger
To enable support for multi-tenancy, run the `alice` or `faber` demo with the `--multitenant` option:
To enable multiple ledger mode, run the `alice` or `faber` demo with the `--multi-ledger` option:
```bash
./run_demo faber --multitenant
./run_demo faber --multi-ledger
```
(This option can be used with both (or either) `alice` and/or `faber`.)
The configuration file for setting up multiple ledgers (for the demo) can be found at `./demo/multiple_ledger_config.yml`.
### Multi-ledger
### Multi-tenancy
To enable multiple ledger mode, run the `alice` or `faber` demo with the `--multi-ledger` option:
To enable support for multi-tenancy, run the `alice` or `faber` demo with the `--multitenant` option:
```bash
./run_demo faber --multi-ledger
./run_demo faber --multitenant
```
The configuration file for setting up multiple ledgers (for the demo) can be found at `./demo/multiple_ledger_config.yml`.
(This option can be used with both (or either) `alice` and/or `faber`.)
You will see an additional menu option to create new sub-wallets (or they can be considered to be "virtual agents").
Stephen Curran <swcurran@gmail.com>