Merge pull request openwallet-foundation#2122 from swcurran/demo-instruction-updates

Update some of the demo Readme and Endorser instructions

Author: ianco

demo/Endorser.md

@@ -2,20 +2,22 @@
 
 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):
 
 ```bash
 TAILS_FILE_COUNT=5 ./run_demo faber --endorser-role author --revocation
 ```
 
-Start up Alcie as normal:
+Start up Alice as normal:
 
 ```bash
 ./run_demo alice
@@ -33,7 +35,7 @@ This approach sets up the endorser roles to allow manual testing using the agent
 - Faber runs as an Endorser (all of Faber's functions - issue credential, request proof, etc.) run normally, since Faber has ledger write access
 - Alice starts up with a DID aith Author privileges (no ledger write access) and Faber is setup as Alice's Endorser
 
-Start a VON Network and a Tails server.
+Start a VON Network and a Tails server using the instructions above.
 
 Start up Faber as Endorser:
 

demo/README.md

@@ -4,13 +4,12 @@ There are several demos available for ACA-Py mostly (but not only) aimed at deve
 
 ## Table of Contents <!-- omit in toc -->
 
-- [The IIWBook Demo](#the-iiwbook-demo)
 - [The Alice/Faber Python demo](#the-alicefaber-python-demo)
   - [Running in a Browser](#running-in-a-browser)
   - [Running in Docker](#running-in-docker)
   - [Running Locally](#running-locally)
     - [Installing Prerequisites](#installing-prerequisites)
-    - [Start a local indy ledger](#start-a-local-indy-ledger)
+    - [Start a local Indy ledger](#start-a-local-indy-ledger)
     - [Genesis File handling](#genesis-file-handling)
     - [Run a local Postgres instance](#run-a-local-postgres-instance)
     - [Optional: Run a von-network ledger browser](#optional-run-a-von-network-ledger-browser)
@@ -20,21 +19,18 @@ There are several demos available for ACA-Py mostly (but not only) aimed at deve
     - [Issuing and Proving Credentials](#issuing-and-proving-credentials)
 - [Additional Options in the Alice/Faber demo](#additional-options-in-the-alicefaber-demo)
   - [Revocation](#revocation)
-  - [Mediation](#mediation)
-  - [Multi-tenancy](#multi-tenancy)
-  - [Multi-ledger](#multi-ledger)
   - [DID Exchange](#did-exchange)
   - [Endorser](#endorser)
   - [Run Indy-SDK Backend](#run-indy-sdk-backend)
+  - [Mediation](#mediation)
+  - [Multi-ledger](#multi-ledger)
+  - [Multi-tenancy](#multi-tenancy)
+  - [Multi-tenancy *with Mediation*!!!](#multi-tenancy-with-mediation)
 - [Learning about the Alice/Faber code](#learning-about-the-alicefaber-code)
 - [OpenAPI (Swagger) Demo](#openapi-swagger-demo)
 - [Performance Demo](#performance-demo)
 - [Coding Challenge: Adding ACME](#coding-challenge-adding-acme)
 
-## The IIWBook Demo
-
-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.
@@ -97,12 +96,16 @@ pip3 install -r demo/requirements.txt
 
 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.
@@ -117,15 +120,29 @@ docker run --name some-postgres -e POSTGRES_PASSWORD=mysecretpassword -d -p 5432
 
 #### Optional: Run a von-network ledger browser
 
-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.
 
 ``` bash
 GENESIS_FILE=/path/to/local-genesis.txt PORT=9000 REGISTER_NEW_DIDS=true python -m server.server
 ```
 
 #### Run the Alice and Faber Controllers/Agents
 
-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:
+
+``` bash
+DEFAULT_POSTGRES=true python3 -m runners.faber --port 8020
+```
+
+``` bash
+DEFAULT_POSTGRES=true python3 -m runners.alice --port 8030
+```
+
+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.
 
 ``` bash
 GENESIS_FILE=/path/to/local-genesis.txt DEFAULT_POSTGRES=true python3 -m runners.faber --port 8020
@@ -135,7 +152,7 @@ GENESIS_FILE=/path/to/local-genesis.txt DEFAULT_POSTGRES=true python3 -m runners
 GENESIS_FILE=/path/to/local-genesis.txt DEFAULT_POSTGRES=true python3 -m runners.alice --port 8030
 ```
 
-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").