From b8b573063702aef6f32ac7682d1265de33814778 Mon Sep 17 00:00:00 2001 From: Viktor Kolomeyko Date: Tue, 3 Jul 2018 17:11:48 +0100 Subject: [PATCH] ENT-2160: Documentation updates for tools we ship with GA release. (#1131) (#1191) (cherry picked from commit 61506c0) --- docs/source/blob-inspector.rst | 15 ++-- docs/source/demobench.rst | 11 ++- docs/source/network-bootstrapper.rst | 17 +++-- docs/source/node-explorer.rst | 100 +++------------------------ 4 files changed, 42 insertions(+), 101 deletions(-) diff --git a/docs/source/blob-inspector.rst b/docs/source/blob-inspector.rst index 1742ee8771..d70063865d 100644 --- a/docs/source/blob-inspector.rst +++ b/docs/source/blob-inspector.rst @@ -6,17 +6,24 @@ disadvantage is the inability to view the contents in a human-friendly manner. T by allowing the contents of a binary blob file (or URL end-point) to be output in either YAML or JSON. It uses ``JacksonSupport`` to do this (see :doc:`json`). -The latest version of the tool can be downloaded from `here `_. +The tool is distributed as part of |release| in the form of runnable JAR "|jar_name|". + +.. |jar_name| replace:: corda-tools-blob-inspector-|version|.jar To run simply pass in the file or URL as the first parameter: -``java -jar blob-inspector.jar `` +.. parsed-literal:: + + > java -jar |jar_name| + +.. + Use the ``--help`` flag for a full list of command line options. -When inspecting your custom data structures, there's no need to include the jars containing the class definitions for them +When inspecting your custom data structures, there is no need to include the jars containing the class definitions for them in the classpath. The blob inspector (or rather the serialization framework) is able to synthesis any classes found in the -blob that aren't on the classpath. +blob that are not on the classpath. SerializedBytes ~~~~~~~~~~~~~~~ diff --git a/docs/source/demobench.rst b/docs/source/demobench.rst index 09f3ea69e3..17a2e27f4b 100644 --- a/docs/source/demobench.rst +++ b/docs/source/demobench.rst @@ -6,13 +6,20 @@ DemoBench is a standalone desktop application that makes it easy to configure an Downloading ----------- -Installers compatible with the latest Corda release can be downloaded from the `Corda website`_. +Operating System specific installers are provided as part of |release| distribution, e.g. for Windows this will be "|installer_name|". -.. _Corda website: https://www.corda.net/downloads +.. |installer_name| replace:: Corda DemoBench-|version|.exe Running DemoBench ----------------- +Run the installer and follow instructions on the screen. +Once installer completes it will start ``Corda DemoBench`` application: + +.. image:: ../../tools/demobench/demobench-initial.png + :scale: 50% + :align: center + Configuring a Node Each node must have a unique name to identify it to the network map service. DemoBench will suggest node names, nearest cities and local port numbers to use. diff --git a/docs/source/network-bootstrapper.rst b/docs/source/network-bootstrapper.rst index e0c3900927..59e05e910c 100644 --- a/docs/source/network-bootstrapper.rst +++ b/docs/source/network-bootstrapper.rst @@ -24,13 +24,18 @@ You can find out more about network maps and network parameters from :doc:`netwo Bootstrapping a test network ~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -The bootstrapper can be downloaded from https://downloads.corda.net/network-bootstrapper-VERSION.jar, where ``VERSION`` -is the Corda version. +The bootstrapper is distributed as part of |release| in the form of runnable JAR file "|jar_name|". + +.. |jar_name| replace:: corda-tools-network-bootstrapper-|version|.jar Create a directory containing a node config file, ending in "_node.conf", for each node you want to create. Then run the following command: -``java -jar network-bootstrapper-VERSION.jar --dir `` +.. parsed-literal:: + + > java -jar |jar_name| --dir + +.. For example running the command on a directory containing these files: @@ -47,7 +52,7 @@ alongside the configuration files in the directory. The directory can also contain CorDapp JARs which will be copied to each node's ``cordapps`` directory. -You can also have the node directories containing their "node.conf" files already laid out. The previous example would be: +You can also have the node directories containing their ``node.conf`` files already laid out. The previous example would be: .. sourcecode:: none @@ -68,10 +73,10 @@ This tool only bootstraps a network. It cannot dynamically update if a new node one has changed something in their node-info, e.g. their P2P address. For this the new node-info file will need to be placed in the other nodes' ``additional-node-infos`` directory. A simple way to do this is to use `rsync `_. However, if it's known beforehand the set of nodes that will eventually form part of the network then all the node directories -can be pregenerated in the bootstrap and only started when needed. +can be pre-generated in the bootstrap and only started when needed. Running the bootstrapper again on the same network will allow a new node to be added or an existing one to have its updated -node-info re-distributed. However this comes at the expense of having to temporarily collect the node directories back +node-info re-distributed. However, this comes at the expense of having to temporarily collect the node directories back together again under a common parent directory. Whitelisting contracts diff --git a/docs/source/node-explorer.rst b/docs/source/node-explorer.rst index 186a1f6b86..3d0966584e 100644 --- a/docs/source/node-explorer.rst +++ b/docs/source/node-explorer.rst @@ -2,108 +2,30 @@ Node Explorer ============= The node explorer provides views into a node's vault and transaction data using Corda's RPC framework. +Node Explorer assumes that "|finance_jar_name|" CorDapp is deployed on the node. The user can execute cash transaction commands to issue and move cash to other parties on the network or exit cash (eg. remove from the ledger) +The tool is distributed in the form of runnable JAR file: "|jar_name|". + +.. |jar_name| replace:: corda-tools-explorer-|version|.jar + +.. |finance_jar_name| replace:: corda-finance-|version|.jar + Running the UI -------------- -**Windows**:: - gradlew.bat tools:explorer:run +.. parsed-literal:: -**Other**:: + > java -jar |jar_name| - ./gradlew tools:explorer:run +.. -Running demo nodes ------------------- - -A demonstration Corda network topology is configured with 5 nodes playing the following roles: - -1. Notary -2. Issuer nodes, representing two fictional central banks (UK Bank Plc issuer of GBP and USA Bank Corp issuer of USD) -3. Participant nodes, representing two users (Alice and Bob) - -When connected to an *Issuer* node, a user can execute cash transaction commands to issue and move cash to itself or other -parties on the network or to exit cash (for itself only). - -When connected to a *Participant* node a user can only execute cash transaction commands to move cash to other parties on the network. - -The Demo Nodes can be started in one of three modes: - -1. Normal - - Fresh clean environment empty of transactions. - Firstly, launch an Explorer instance to login to one of the Issuer nodes and issue some cash to the other participants (Bob and Alice). - Then launch another Explorer instance to login to a participant node and start making payments (eg. move cash). - You will only be able to exit (eg. redeem from the ledger) cash as an issuer node. - -**Windows**:: - - gradlew.bat tools:explorer:runDemoNodes - -**Other**:: - - ./gradlew tools:explorer:runDemoNodes - -2. Simulation - - In this mode Nodes will automatically commence executing commands as part of a random generation process. - The simulation start with pre-allocating chunks of cash to each of the party in 2 currencies (USD, GBP), then it enter a loop to generate random events. - In each iteration, the issuers will execute a Cash Issue or Cash Exit command (at a 9:1 ratio) and a random party will execute a move of cash to another random party. - -**Windows**:: - - gradlew.bat tools:explorer:runSimulationNodes - -**Other**:: - - ./gradlew tools:explorer:runSimulationNodes - -.. _flow_triage: - -3. Flow triage - - Once again, building on the demonstration Corda network topology described above, this scenario mode triggers - an exception within a flow which can then be visualized using the "Flow Triage" panel within the Explorer. - The "Flow Triage" panel will be enhanced in the future to enable operators to take corrective actions upon flow failures - (eg. retry, terminate, amend and replay) - -**Windows:** - - gradlew.bat tools:explorer:runFlowTriageNodes - -**Other:** - - ./gradlew tools:explorer:runFlowTriageNodes - -.. note:: 5 Corda nodes will be created on the following port on localhost by default. - - * Notary -> 20005 (Does not accept logins) - * UK Bank Plc -> 20011 (*Issuer node*) - * USA Bank Corp -> 20008 (*Issuer node*) - * Alice -> 20017 - * Bob -> 20014 - -Explorer login credentials to the Issuer nodes are defaulted to ``manager`` and ``test``. -Explorer login credentials to the Participants nodes are defaulted to ``user1`` and ``test``. -Please note you are not allowed to login to the notary. - -.. note:: When you start the nodes in Windows using the command prompt, they might not be killed when you close the - window or terminate the task. If that happens you need to manually terminate the Java processes running the nodes. - -.. note:: Alternatively, you may start the demo nodes from within IntelliJ using either of the run configurations - ``Explorer - demo nodes`` or ``Explorer - demo nodes (simulation)`` - -.. note:: It is also possible to start the Explorer GUI from IntelliJ via ``Explorer - GUI`` run configuration, provided that the optional TornadoFX plugin has been installed first. - -.. note:: Use the Explorer in conjunction with the Trader Demo and Bank of Corda samples to use other *Issuer* nodes. - Interface --------- Login User can login to any Corda node using the explorer. Alternatively, ``gradlew explorer:runDemoNodes`` can be used to start up demo nodes for testing. - Corda node address, username and password are required for login, the address is defaulted to localhost:0 if leave blank. + Corda node address, username and password are required for login, the address is defaulted to ``localhost:0`` if left blank. Username and password can be configured via the ``rpcUsers`` field in node's configuration file. .. image:: resources/explorer/login.png