diff --git a/docs/source/demobench.rst b/docs/source/demobench.rst new file mode 100644 index 0000000000..53d0de5ebb --- /dev/null +++ b/docs/source/demobench.rst @@ -0,0 +1,95 @@ +DemoBench +========= + +DemoBench is a standalone desktop application that makes it easy to configure and launch local Corda nodes. It is useful for training sessions, demos or just experimentation. + +Downloading +----------- + +Installers compatible with the latest Corda release will soon be downloadable from the R3 website. + +Running DemoBench +----------------- + +Configuring a Node + Each node must have a unique name to identify it to the network map service. DemoBench will also suggest local port numbers to use. + + The first node will host the network map service, and therefore *must* be a notary. Hence only notary services will be available to be selected in the ``Services`` list. For subsequent nodes you may also select any of Corda's other built-in services. + +.. note:: Press ``Ctrl``/``Cmd`` and then click with the mouse to select multiple services, and also to deselect a service again. + +.. + + Press the ``Create Node`` button to launch the Corda node with your configuration. + +Running Nodes + DemoBench launches each new node in a terminal emulator. The ``View Database``, ``Launch Explorer`` and ``Launch WebServer`` buttons will all be disabled until the node has finished booting. DemoBench will then display simple statistics about the node such as its cash balance. + +.. warning:: After switching tabs, it may currently be necessary to click on the new tab panel before its contents update correctly. This is a BUG and we're working on it. + +.. + + +Exiting DemoBench + When you terminate DemoBench, it will automatically shut down any nodes and explorers that it has launched and then exit. + +Profiles + You can save all of DemoBench's currently running nodes into a profile, which is a ``ZIP`` file with the following layout, e.g.: + +.. parsed-literal:: + + notary/ + node.conf + plugins/ + banka/ + node.conf + plugins/ + bankb/ + node.conf + plugins/ + example-cordapp.jar + ... + +.. + + When DemoBench reloads this profile it will close any nodes that it is currently running and then launch these new nodes instead. Note that the ``node.conf`` files within each profile are JSON/HOCON format, and so can be extracted and edited as required. + +Building the Installers +----------------------- + +There are three scripts in the ``tools/demobench`` directory: + + #. ``package-demobench-exe.bat`` (Windows) + #. ``package-demobench-dmg.sh`` (MacOS) + #. ``package-demobench-rpm.sh`` (Fedora/Linux) + +Each script can only be run on its target platform, and each expects the platform's installation tools already to be available. + + #. Windows: `Inno Setup 5+ `_ + #. MacOS: The packaging tools should be available automatically. The DMG contents will also be signed if the packager finds a valid ``Developer ID Application`` certificate on the keyring. You can create such a certificate by generating a Certificate Signing Request and then asking your local "Apple team agent" to upload it to the Apple Developer portal. (See `here `_.) + #. Fedora/Linux: ``rpm-build`` packages. + +You will also need to define the environment variable ``JAVA_HOME`` to point to the same JDK that you use to run Gradle. The installer will be written to the ``tools/demobench/build/javapackage/bundles`` directory, and can be installed like any other application for your platform. + +Developer Notes +--------------- + +Developers wishing to run DemoBench *without* building a new installer each time can install it locally using Gradle: + +.. parsed-literal:: + + $ gradlew tools:demobench:installDist + $ cd tools/demobench/build/install/demobench + $ bin/demobench + +.. + + +Unfortunately, DemoBench's ``$CLASSPATH`` may be too long for the Windows shell . In which case you can still run DemoBench as follows: + +.. parsed-literal:: + + > java -Djava.util.logging.config.class=net.corda.demobench.config.LoggingConfig -jar lib/demobench-$version.jar + +.. + diff --git a/docs/source/index.rst b/docs/source/index.rst index e564df6d1e..d62262e3b4 100644 --- a/docs/source/index.rst +++ b/docs/source/index.rst @@ -124,6 +124,7 @@ Documentation Contents: :caption: Appendix loadtesting + demobench setting-up-a-corda-network secure-coding-guidelines release-process diff --git a/docs/source/release-notes.rst b/docs/source/release-notes.rst index c58479493f..c191d7f14f 100644 --- a/docs/source/release-notes.rst +++ b/docs/source/release-notes.rst @@ -13,6 +13,14 @@ the node. The Corda Shell is based on the popular `CRaSH project