mirror of
https://github.com/corda/corda.git
synced 2025-02-10 21:01:27 +00:00
Updates Network Builder docs. (#3708)
* Initial improvements. * Clean up. * Mainly GUI updates. * Changes stray BankOfCorda reference.
This commit is contained in:
Joel Dudley
GitHub
parent
6453f2e053
commit
723ec89150
@ -1,27 +1,35 @@
|
||||
Corda Network Builder
|
||||
=====================
|
||||
|
||||
The corda network builder is a way to build dynamic networks for testing. It leverages docker and containers to abstract
|
||||
as much of the complexity of managing a distributed network away from the user.
|
||||
.. contents::
|
||||
|
||||
At the moment, there are integrations for `docker` and `azure container service`
|
||||
The Corda Network Builder is a tool for building Corda networks for testing purposes. It leverages Docker and
|
||||
containers to abstract the complexity of managing a distributed network away from the user.
|
||||
|
||||
Currently, the network you build will either be made up of local ``docker`` nodes *or* of nodes spread across Azure
|
||||
containers.
|
||||
|
||||
The Corda Network Builder can be downloaded from
|
||||
https://ci-artifactory.corda.r3cev.com/artifactory/corda-releases/net/corda/corda-network-builder/X.Y-corda/corda-network-builder-X.Y-corda-executable.jar,
|
||||
where ``X`` is the major Corda version and ``Y`` is the minor Corda version.
|
||||
|
||||
.. _pre-requisites:
|
||||
|
||||
Prerequisites
|
||||
-------------
|
||||
|
||||
:docker:
|
||||
docker > 17.12.0-ce
|
||||
* **Docker:** docker > 17.12.0-ce
|
||||
* **Azure:** authenticated az-cli >= 2.0 (see: https://docs.microsoft.com/en-us/cli/azure/install-azure-cli?view=azure-cli-latest)
|
||||
|
||||
:azure:
|
||||
authenticated az-cli >= 2.0 (see: https://docs.microsoft.com/en-us/cli/azure/install-azure-cli?view=azure-cli-latest)
|
||||
.. _creating_the_base_nodes:
|
||||
|
||||
Building a network
|
||||
------------------
|
||||
Creating the base nodes
|
||||
-----------------------
|
||||
|
||||
The network builder uses node docker images as the base for all other operations. A "node" is anything that satisfies
|
||||
the following layout
|
||||
The network builder uses a set of nodes as the base for all other operations. A node is anything that satisfies
|
||||
the following layout:
|
||||
|
||||
::
|
||||
.. sourcecode:: shell
|
||||
|
||||
-
|
||||
-- node.conf
|
||||
@ -29,30 +37,54 @@ the following layout
|
||||
-- cordapps/
|
||||
|
||||
|
||||
An easy way to build a compliant set of nodes is to use the ``deployNodes`` utility. In this document, we will be using the output of ``deployNodes`` of the ``bank-of-corda-demo`` sample available in the main corda repository.
|
||||
An easy way to build a valid set of nodes is by running ``deployNodes``. In this document, we will be using
|
||||
the output of running ``deployNodes`` for the `Example CorDapp <https://github.com/corda/cordapp-example>`_:
|
||||
|
||||
1. ``git clone https://github.com/corda/cordapp-example``
|
||||
2. ``cd cordapp-example``
|
||||
3. ``./gradlew clean deployNodes``
|
||||
|
||||
Building a network via the command line
|
||||
---------------------------------------
|
||||
|
||||
Starting the nodes
|
||||
^^^^^^^^^^^^^^^^^^
|
||||
|
||||
Quickstart Local Docker
|
||||
~~~~~~~~~~~~~~~~~~~~~~~
|
||||
|
||||
1. ``./gradlew clean samples:bank-of-corda-demo:deployNodes``
|
||||
2. ``cd samples/bank-of-corda-demo/build/nodes``
|
||||
3. ``java -jar <network-builder-jar> -d .``
|
||||
4. ``docker ps``
|
||||
1. ``cd kotlin-source/build/nodes``
|
||||
2. ``java -jar <path/to/network-builder-jar> -d .``
|
||||
|
||||
The following output should be displayed
|
||||
If you run ``docker ps`` to see the running containers, the following output should be displayed:
|
||||
|
||||
::
|
||||
.. sourcecode:: shell
|
||||
|
||||
CONTAINER ID IMAGE COMMAND CREATED STATUS PORTS NAMES
|
||||
8b65c104ba7c node-bigcorporation:corda-network "/run-corda.sh" 14 seconds ago Up 13 seconds 0.0.0.0:32788->10003/tcp, 0.0.0.0:32791->10005/tcp, 0.0.0.0:32790->10020/tcp, 0.0.0.0:32789->12222/tcp bigcorporation0
|
||||
3a7af5543c3a node-bankofcorda:corda-network "/run-corda.sh" 14 seconds ago Up 13 seconds 0.0.0.0:32787->10003/tcp, 0.0.0.0:32786->10005/tcp, 0.0.0.0:32785->10020/tcp, 0.0.0.0:32784->12222/tcp bankofcorda0
|
||||
a7b84444feed node-notaryservice:corda-network "/run-corda.sh" 23 seconds ago Up 22 seconds 0.0.0.0:32783->10003/tcp, 0.0.0.0:32782->10005/tcp, 0.0.0.0:32781->10020/tcp, 0.0.0.0:32780->12222/tcp notaryservice0
|
||||
CONTAINER ID IMAGE COMMAND CREATED STATUS PORTS NAMES
|
||||
406868b4ba69 node-partyc:corda-network "/run-corda.sh" 17 seconds ago Up 16 seconds 0.0.0.0:32902->10003/tcp, 0.0.0.0:32895->10005/tcp, 0.0.0.0:32898->10020/tcp, 0.0.0.0:32900->12222/tcp partyc0
|
||||
4546a2fa8de7 node-partyb:corda-network "/run-corda.sh" 17 seconds ago Up 17 seconds 0.0.0.0:32896->10003/tcp, 0.0.0.0:32899->10005/tcp, 0.0.0.0:32901->10020/tcp, 0.0.0.0:32903->12222/tcp partyb0
|
||||
c8c44c515bdb node-partya:corda-network "/run-corda.sh" 17 seconds ago Up 17 seconds 0.0.0.0:32894->10003/tcp, 0.0.0.0:32897->10005/tcp, 0.0.0.0:32892->10020/tcp, 0.0.0.0:32893->12222/tcp partya0
|
||||
cf7ab689f493 node-notary:corda-network "/run-corda.sh" 30 seconds ago Up 31 seconds 0.0.0.0:32888->10003/tcp, 0.0.0.0:32889->10005/tcp, 0.0.0.0:32890->10020/tcp, 0.0.0.0:32891->12222/tcp notary0
|
||||
|
||||
to interact with the nodes, it is possible to ssh into the nodes via the port 12222 mapping, for example to ssh into the `bankofcorda0` node
|
||||
Quickstart Remote Azure
|
||||
~~~~~~~~~~~~~~~~~~~~~~~
|
||||
|
||||
::
|
||||
1. ``cd kotlin-source/build/nodes``
|
||||
2. ``java -jar <path/to/network-builder-jar> -b AZURE -d .``
|
||||
|
||||
ssh bankUser@localhost -p 32784
|
||||
.. note:: The Azure configuration is handled by the az-cli utility. See the :ref:`pre-requisites`.
|
||||
|
||||
.. _interacting_with_the_nodes:
|
||||
|
||||
Interacting with the nodes
|
||||
^^^^^^^^^^^^^^^^^^^^^^^^^^
|
||||
|
||||
You can interact with the nodes by SSHing into them on the port that is mapped to 12222. For example, to SSH into the
|
||||
``partya0`` node, you would run:
|
||||
|
||||
.. sourcecode:: shell
|
||||
|
||||
ssh user1@localhost -p 32893
|
||||
Password authentication
|
||||
Password:
|
||||
|
||||
@ -62,41 +94,92 @@ to interact with the nodes, it is possible to ssh into the nodes via the port 12
|
||||
|
||||
>>> run networkMapSnapshot
|
||||
[
|
||||
{"legalIdentities":[{"name":"O=BankOfCorda, L=London, C=GB"}],"addresses":["bankofcorda0:10020"],"serial":1531841642785,"platformVersion":3},
|
||||
{"legalIdentities":[{"name":"O=Notary Service, L=Zurich, C=CH"}],"addresses":["notaryservice0:10020"],"serial":1531841631144,"platformVersion":3},
|
||||
{"legalIdentities":[{"name":"O=BigCorporation, L=New York, C=US"}],"addresses":["bigcorporation0:10020"],"serial":1531841642864,"platformVersion":3}
|
||||
{ "addresses" : [ "partya0:10020" ], "legalIdentitiesAndCerts" : [ "O=PartyA, L=London, C=GB" ], "platformVersion" : 3, "serial" : 1532701330613 },
|
||||
{ "addresses" : [ "notary0:10020" ], "legalIdentitiesAndCerts" : [ "O=Notary, L=London, C=GB" ], "platformVersion" : 3, "serial" : 1532701305115 },
|
||||
{ "addresses" : [ "partyc0:10020" ], "legalIdentitiesAndCerts" : [ "O=PartyC, L=Paris, C=FR" ], "platformVersion" : 3, "serial" : 1532701331608 },
|
||||
{ "addresses" : [ "partyb0:10020" ], "legalIdentitiesAndCerts" : [ "O=PartyB, L=New York, C=US" ], "platformVersion" : 3, "serial" : 1532701330118 }
|
||||
]
|
||||
|
||||
>>>
|
||||
|
||||
now that the node images have been built, it is possible to add nodes reusing the same images. To add a node reusing the `BankOfCorda` base image.
|
||||
Adding additional nodes
|
||||
^^^^^^^^^^^^^^^^^^^^^^^
|
||||
|
||||
``java -jar <bootstrapper-jar> --add "BankOfCorda=O=WayTooBigToFailBank,L=London,C=GB"``
|
||||
It is possible to add additional nodes to the network by reusing the nodes you built earlier. For example, to add a
|
||||
node by reusing the existing ``PartyA`` node, you would run:
|
||||
|
||||
And to confirm the node has been started correctly in the previously connected ssh session
|
||||
``java -jar <network-builder-jar> --add "PartyA=O=PartyZ,L=London,C=GB"``
|
||||
|
||||
::
|
||||
To confirm the node has been started correctly, run the following in the previously connected SSH session:
|
||||
|
||||
Tue Jul 17 15:47:14 GMT 2018>>> run networkMapSnapshot
|
||||
[
|
||||
{"legalIdentities":[{"name":"O=BankOfCorda, L=London, C=GB"}],"addresses":["bankofcorda0:10020"],"serial":1531841642785,"platformVersion":3},
|
||||
{"legalIdentities":[{"name":"O=Notary Service, L=Zurich, C=CH"}],"addresses":["notaryservice0:10020"],"serial":1531841631144,"platformVersion":3},
|
||||
{"legalIdentities":[{"name":"O=BigCorporation, L=New York, C=US"}],"addresses":["bigcorporation0:10020"],"serial":1531841642864,"platformVersion":3},
|
||||
{"legalIdentities":[{"name":"O=WayTooBigToFailBank, L=London, C=GB"}],"addresses":["bankofcorda1:10020"],"serial":1531842358730,"platformVersion":3}
|
||||
]
|
||||
.. sourcecode:: shell
|
||||
|
||||
Quickstart Remote Azure
|
||||
~~~~~~~~~~~~~~~~~~~~~~~
|
||||
Tue Jul 17 15:47:14 GMT 2018>>> run networkMapSnapshot
|
||||
[
|
||||
{ "addresses" : [ "partya0:10020" ], "legalIdentitiesAndCerts" : [ "O=PartyA, L=London, C=GB" ], "platformVersion" : 3, "serial" : 1532701330613 },
|
||||
{ "addresses" : [ "notary0:10020" ], "legalIdentitiesAndCerts" : [ "O=Notary, L=London, C=GB" ], "platformVersion" : 3, "serial" : 1532701305115 },
|
||||
{ "addresses" : [ "partyc0:10020" ], "legalIdentitiesAndCerts" : [ "O=PartyC, L=Paris, C=FR" ], "platformVersion" : 3, "serial" : 1532701331608 },
|
||||
{ "addresses" : [ "partyb0:10020" ], "legalIdentitiesAndCerts" : [ "O=PartyB, L=New York, C=US" ], "platformVersion" : 3, "serial" : 1532701330118 },
|
||||
{ "addresses" : [ "partya1:10020" ], "legalIdentitiesAndCerts" : [ "O=PartyZ, L=London, C=GB" ], "platformVersion" : 3, "serial" : 1532701630861 }
|
||||
]
|
||||
|
||||
1. ``./gradlew clean samples:bank-of-corda-demo:deployNodes``
|
||||
2. ``cd samples/bank-of-corda-demo/build/nodes``
|
||||
3. ``java -jar <network-builder-jar> -b AZURE -d .``
|
||||
Building a network in Graphical User Mode
|
||||
-----------------------------------------
|
||||
|
||||
.. note:: Azure configuration is handled per the az-cli utility, see pre-reqs at the start of the document
|
||||
The Corda Network Builder also provides a GUI for when automated interactions are not required. To launch it, run
|
||||
``java -jar <path/to/network-builder-jar> -g``.
|
||||
|
||||
Graphical User Mode
|
||||
~~~~~~~~~~~~~~~~~~~
|
||||
Starting the nodes
|
||||
^^^^^^^^^^^^^^^^^^
|
||||
|
||||
The corda network builder also provides a GUI for when automated interactions are not required to launch this run
|
||||
``java -jar <network-builder-jar> -g``
|
||||
1. Click ``Open nodes ...`` and select the folder where you built your nodes in :ref:`creating_the_base_nodes` and
|
||||
click ``Open``
|
||||
2. Select ``Local Docker`` or ``Azure``
|
||||
3. Click ``Build``
|
||||
|
||||
.. note:: The Azure configuration is handled by the az-cli utility. See the :ref:`pre-requisites`.
|
||||
|
||||
All the nodes should eventually move to a ``Status`` of ``INSTANTIATED``. If you run ``docker ps`` from the terminal to
|
||||
see the running containers, the following output should be displayed:
|
||||
|
||||
.. sourcecode:: shell
|
||||
|
||||
CONTAINER ID IMAGE COMMAND CREATED STATUS PORTS NAMES
|
||||
406868b4ba69 node-partyc:corda-network "/run-corda.sh" 17 seconds ago Up 16 seconds 0.0.0.0:32902->10003/tcp, 0.0.0.0:32895->10005/tcp, 0.0.0.0:32898->10020/tcp, 0.0.0.0:32900->12222/tcp partyc0
|
||||
4546a2fa8de7 node-partyb:corda-network "/run-corda.sh" 17 seconds ago Up 17 seconds 0.0.0.0:32896->10003/tcp, 0.0.0.0:32899->10005/tcp, 0.0.0.0:32901->10020/tcp, 0.0.0.0:32903->12222/tcp partyb0
|
||||
c8c44c515bdb node-partya:corda-network "/run-corda.sh" 17 seconds ago Up 17 seconds 0.0.0.0:32894->10003/tcp, 0.0.0.0:32897->10005/tcp, 0.0.0.0:32892->10020/tcp, 0.0.0.0:32893->12222/tcp partya0
|
||||
cf7ab689f493 node-notary:corda-network "/run-corda.sh" 30 seconds ago Up 31 seconds 0.0.0.0:32888->10003/tcp, 0.0.0.0:32889->10005/tcp, 0.0.0.0:32890->10020/tcp, 0.0.0.0:32891->12222/tcp notary0
|
||||
|
||||
Interacting with the nodes
|
||||
^^^^^^^^^^^^^^^^^^^^^^^^^^
|
||||
|
||||
See :ref:`interacting_with_the_nodes`.
|
||||
|
||||
Adding additional nodes
|
||||
^^^^^^^^^^^^^^^^^^^^^^^
|
||||
|
||||
It is possible to add additional nodes to the network by reusing the nodes you built earlier. For example, to add a
|
||||
node by reusing the existing ``PartyA`` node, you would:
|
||||
|
||||
1. Select ``partya`` in the dropdown
|
||||
2. Click ``Add Instance``
|
||||
3. Specify the new node's X500 name and click ``OK``
|
||||
|
||||
If you click on ``partya`` in the pane, you should see an additional instance listed in the sidebar. To confirm the
|
||||
node has been started correctly, run the following in the previously connected SSH session:
|
||||
|
||||
.. sourcecode:: shell
|
||||
|
||||
Tue Jul 17 15:47:14 GMT 2018>>> run networkMapSnapshot
|
||||
[
|
||||
{ "addresses" : [ "partya0:10020" ], "legalIdentitiesAndCerts" : [ "O=PartyA, L=London, C=GB" ], "platformVersion" : 3, "serial" : 1532701330613 },
|
||||
{ "addresses" : [ "notary0:10020" ], "legalIdentitiesAndCerts" : [ "O=Notary, L=London, C=GB" ], "platformVersion" : 3, "serial" : 1532701305115 },
|
||||
{ "addresses" : [ "partyc0:10020" ], "legalIdentitiesAndCerts" : [ "O=PartyC, L=Paris, C=FR" ], "platformVersion" : 3, "serial" : 1532701331608 },
|
||||
{ "addresses" : [ "partyb0:10020" ], "legalIdentitiesAndCerts" : [ "O=PartyB, L=New York, C=US" ], "platformVersion" : 3, "serial" : 1532701330118 },
|
||||
{ "addresses" : [ "partya1:10020" ], "legalIdentitiesAndCerts" : [ "O=PartyZ, L=London, C=GB" ], "platformVersion" : 3, "serial" : 1532701630861 }
|
||||
]
|
||||
|
||||
Shutting down the nodes
|
||||
-----------------------
|
||||
|
||||
Run ``docker kill $(docker ps -q)`` to kill all running Docker processes.
|
||||
@ -4,6 +4,7 @@ Tools
|
||||
.. toctree::
|
||||
:maxdepth: 1
|
||||
|
||||
network-builder
|
||||
blob-inspector
|
||||
network-simulator
|
||||
demobench
|
||||
|
||||
Loading…
x
Reference in New Issue
Block a user