From 720bb55827ff84fc8f749f34aa22263a72fd1657 Mon Sep 17 00:00:00 2001 From: Andras Slemmer Date: Mon, 21 Nov 2016 16:39:46 +0000 Subject: [PATCH] docs: setting-up-a-corda-network --- docs/generate-docsite.sh | 2 +- .../src/main/resources/example-node.conf | 11 ++++ .../net/corda/docs/ExampleNodeConfTest.kt | 23 +++++++ docs/source/setting-up-a-corda-network.rst | 63 +++++++++++++++++++ docs/source/tutorial-clientrpc-api.rst | 4 +- 5 files changed, 101 insertions(+), 2 deletions(-) create mode 100644 docs/source/example-code/src/main/resources/example-node.conf create mode 100644 docs/source/example-code/src/test/kotlin/net/corda/docs/ExampleNodeConfTest.kt create mode 100644 docs/source/setting-up-a-corda-network.rst diff --git a/docs/generate-docsite.sh b/docs/generate-docsite.sh index b3bc4405ee..51c3e4e1d8 100755 --- a/docs/generate-docsite.sh +++ b/docs/generate-docsite.sh @@ -21,7 +21,7 @@ fi virtualenv -p python2.7 virtualenv fi . virtualenv/bin/activate - if [ ! -d "docs/virtualenv/lib/python2.7/site-packages/sphinx" ] + if [ ! -d "virtualenv/lib/python2.7/site-packages/sphinx" ] then echo "Installing pip dependencies ... " pip install -r requirements.txt diff --git a/docs/source/example-code/src/main/resources/example-node.conf b/docs/source/example-code/src/main/resources/example-node.conf new file mode 100644 index 0000000000..402694896a --- /dev/null +++ b/docs/source/example-code/src/main/resources/example-node.conf @@ -0,0 +1,11 @@ +basedir : "./standalone/regular-node" +myLegalName : "Some Node" +nearestCity : "London" +keyStorePassword : "cordacadevpass" +trustStorePassword : "trustpass" +artemisAddress : "cordaload-node1:31337" +webAddress : "localhost:31339" +extraAdvertisedServiceIds: "" +useHTTPS : false +devMode : false +networkMapAddress : "cordaload-nameserver:31337" diff --git a/docs/source/example-code/src/test/kotlin/net/corda/docs/ExampleNodeConfTest.kt b/docs/source/example-code/src/test/kotlin/net/corda/docs/ExampleNodeConfTest.kt new file mode 100644 index 0000000000..b4ab14cca8 --- /dev/null +++ b/docs/source/example-code/src/test/kotlin/net/corda/docs/ExampleNodeConfTest.kt @@ -0,0 +1,23 @@ +package net.corda.docs + +import net.corda.node.services.config.ConfigHelper +import net.corda.node.services.config.FullNodeConfiguration +import org.junit.Test +import java.nio.file.Paths +import kotlin.reflect.declaredMemberProperties + +class ExampleNodeConfTest { + @Test + fun exampleNodeConfParsesFine() { + val configResource = ExampleNodeConfTest::class.java.classLoader.getResource("example-node.conf") + val nodeConfig = FullNodeConfiguration( + ConfigHelper.loadConfig( + baseDirectoryPath = Paths.get("some-example-base-dir"), + configFileOverride = Paths.get(configResource.toURI()) + ) + ) + nodeConfig.javaClass.kotlin.declaredMemberProperties.forEach { member -> + member.get(nodeConfig) + } + } +} \ No newline at end of file diff --git a/docs/source/setting-up-a-corda-network.rst b/docs/source/setting-up-a-corda-network.rst new file mode 100644 index 0000000000..448cee750d --- /dev/null +++ b/docs/source/setting-up-a-corda-network.rst @@ -0,0 +1,63 @@ +A Corda network + + +Introduction - What is a corda network? +======================================================== + +A Corda network consists of a number of machines running ``node``s, including a single node operating as the network map service. These nodes communicate using persistent protocols in order to create and validate transactions. + +There are four broader categories of functionality one such node may have. These pieces of functionality are provided as services, and one node may run several of them. + +* Network map: The node running the network map provides a way to resolve identities to physical node addresses. +* Notary: Nodes running a notary service witness state spends and have the final say in whether a transaction is a double-spend or not. +* Oracle: Nodes providing some oracle functionality like exchange rate or interest rate witnesses. +* Regular node: All nodes have a vault and may start protocols communicating with other nodes, notaries and oracles and evolve their private ledger. + +Setting up your own network +=========================== + +Certificates +------------ + +All node certificates' root must be the same. Later R3 will provide the root for production use, but for testing you can use ``certSigningRequestUtility.jar`` to generate a node certificate with a fixed test root: + +.. sourcecode:: bash + + # Build the jars + ./gradlew buildCordaJAR + # Generate certificate + java -jar build/libs/certSigningRequestUtility.jar --base-dir NODE_DIRECTORY/ + +Configuration +------------- + +A node can be configured by adding/editing ``node.conf`` in the node's directory. + +An example configuration: + +.. literalinclude:: example-code/src/main/resources/example-node.conf + :language: cfg + +The most important fields regarding network configuration are: + +* ``artemisAddress``: This specifies a host and port. Note that the address bound will **NOT** be ``cordaload-node1``, but rather ``::`` (all addresses on all interfaces). The hostname specified is the hostname *that must be externally resolvable by other nodes in the network*. In the above configuration this is the resolvable name of a node in a vpn. +* ``webAddress``: The address the webserver should bind. Note that the port should be distinct from that of ``artemisAddress``. +* ``networkMapAddress``: The resolvable name and artemis port of the network map node. Note that if this node itself is to be the network map this field should not be specified. + +Starting the nodes +------------------ + +You may now start the nodes in any order. You should see lots of log lines about the startup. + +Note that the node is not fully started until it has successfully registered with the network map! A good way of determining whether a node is up is to check whether its ``webAddress`` is bound. + +In terms of process management there is no pre-described method, you may start the jars by hand or perhaps use systemd and friends. + +Connecting to the nodes +----------------------- + +Once a node has started up successfully you may connect to it as a client to initiate protocols/query state etc. Depending on your network setup you may need to tunnel to do this remotely. + +See the :doc:`tutorial-clientrpc-api` on how to establish an RPC link, or you can use the web apis as well. + +Sidenote: A client is always associated with a single node with a single identity, which only sees their part of the ledger. diff --git a/docs/source/tutorial-clientrpc-api.rst b/docs/source/tutorial-clientrpc-api.rst index 1cbdf18987..58e3a2fdb7 100644 --- a/docs/source/tutorial-clientrpc-api.rst +++ b/docs/source/tutorial-clientrpc-api.rst @@ -66,6 +66,8 @@ The RPC we need to initiate a Cash transaction is ``startFlowDynamic`` which may Finally we have everything in place: we start a couple of nodes, connect to them, and start creating transactions while listening on successfully created ones, which are dumped to the console. We just need to run it!: +.. sourcecode:: bash + # Build the example ./gradlew docs/source/example-code:installDist # Start it @@ -94,4 +96,4 @@ requests or responses with the `Kryo` instance RPC uses. Here's an example of h See more on plugins in :doc:`creating-a-cordapp`. .. warning:: We will be replacing the use of Kryo in RPC with a stable message format and this will mean that this plugin - customisation point will either go away completely or change. \ No newline at end of file + customisation point will either go away completely or change.