Welcome to Protocol! This top-level repo was designed to help developers launch the full Kiva Protocol system locally on their machines. After all, who doesn't love a good demo?
Kiva Protocol uses Hyperledger Aries - if you haven't heard of it, or just want a refresher, feel free to check out the Aries Cloud Agent Python (ACA-Py) demo for an idea of what is possible with this tech.
You will need to install a few things on your machine before you can run this code package on your own. Here's the list along with suggested version numbers. You do you. :)
For Docker, we recommend increasing its allocated resources to:
For Docker docs
We will be referencing the following GitHub repos several times. Though you should be able to install all the relevant code without them, here are the links:
protocol-demo
aries-guardianship-agency
aries-key-guardian
guardian-bio-auth
protocol-gateway
protocol-common (optional)
aries-controller (optional)
protocol-all
directory, and then move into the directory.mkdir protocol-all
cd protocol-all
The idea here is that we want some top level folder on your machine that contains all our repos in one place
NOTE: Unless specified, always run commands from within the protocol-all
directory
git clone https://github.com/kiva/protocol-demo
./protocol-demo/scripts/get_code.sh
./protocol-demo/scripts/dummy_env.sh
./protocol-demo/scripts/npm_setup.sh
Note: if this is your first time you'll need to manually pull the latest bcgov image:
docker pull bcgovimages/aries-cloudagent:py36-1.16-1_0.7.1
./protocol-demo/scripts/simple_build.sh
If you've tried this demo before, you may have older instances of the agents running. If you need to clean up your containers, you can run the following command. (This will delete ALL Docker container instances. You've been warned.)
docker ps -aq | xargs docker rm -f
docker network prune -f
The simple demo includes the minimum pieces to spin up agents and run through the issuing and verifying flows with them. Please note that you MUST complete every step of the Scripted Setup section before you try this.
cd protocol-demo
./scripts/simple_start.sh
npm run test
./scripts/simple_stop.sh
The full stack demo includes the Guardianship system which includes authentication methods like fingerprint scanning to control agents.
This requires some additional setup scripts.
protocol-all
directory run./protocol-demo/scripts/java_setup.sh
./protocol-demo/scripts/full_build.sh
cd protocol-demo
./scripts/full_start.sh
npm run test
./scripts/full_stop.sh
Kiva has created another package called SSIrius, which is designed to be an easy-to-use, flexible UI for doing all sorts of SSI transactions.
Kiva has deployed a Guardianship Gateway for you to play with, but if you'd like to use your local build of the Protocol backend instead, that's absolutely an option.
Check out the SSIrius repo, and then in protocol-all
(or anywhere else - again, you do you :) ), run the following command.
git clone https://github.com/kiva/ssi-wizard-sdk.git
Refer to the SSIrius documentation for information on how to get started.
Once you have the protocol-demo
scripts running, there will be a Gateway URL running on your local machine on port 8080.
In your checked out SSIrius repo, go ahead and replace any instances of https://sandbox-gateway.protocol-prod.kiva.org
with http://localhost:8080
.
ngrok
If you're not going to be trying out QR code scanning, you can skip this section. If you are, you'll need to install ngrok
in order to support communication via the Cloud Mediator between the SSIrius UI and your Mobile Wallet.
Fortunately, ngrok
is very cool and very easy to install (though you will need to sign up for a free account).
Once you're ready to roll with ngrok
, run the following command.
./ngrok http 3010
Then, in the aries-guardianship-agency/dummy.env
and protocol-demo/docker-compose.yml
files, replace the PUBLIC_URL
variable's value with the URL generated by ngrok
.
Unfortunately, once you've done this you'll need to run through the setup steps again, but we promise it's much quicker the second time around.