Merged in mnesbit-document-corda-configuration (pull request #312)

Add some documentation of the configuration options of the standalone corda.jar

docs/source/corda-configuration-files.rst

@@ -0,0 +1,116 @@
+The Corda Configuration File
+============================
+
+Configuration File Location
+---------------------------
+
+The Corda all in one ``corda.jar`` file is generated by the ``gradle buildCordaJAR`` task and defaults to reading configuration from a ``node.conf`` file in the present working directory.
+This behaviour can be overidden using the ``--config-file`` command line option to target configuration files with different names, or different file location (relative paths are relative to the current working directory).
+Also, the ``--base-directory`` command line option alters the Corda node workspace location and if specified a ``node.conf`` configuration file is then expected in the root of the workspace.
+
+The configuration file templates used for the ``gradle installTemplateNodes`` task are to be found in the ``/config/dev`` folder. Also note that there is a basic set of defaults loaded from
+the built in resource file ``/node/src/main/resources/reference.conf`` of the ``:node`` gradle module. All properties in this can be overidden in the file configuration
+and for rarely changed properties this defaulting allows the property to be excluded from the configuration file.
+
+Configuration File Format
+-------------------------
+
+Corda uses the Typesafe configuration library to parse the configuration see the `typesafe config on Github <https://github.com/typesafehub/config/>`_  the format of the configuration files can be simple JSON, but for the more powerful substitution features
+uses HOCON format see `HOCON documents <https://github.com/typesafehub/config/blob/master/HOCON.md>`_
+
+Configuration File Examples
+--------------------------
+
+General node configuration file for hosting the IRSDemo services.
+
+.. code-block:: text
+
+	basedir : "./nodea"
+	myLegalName : "Bank A"
+	nearestCity : "London"
+	keyStorePassword : "cordacadevpass"
+	trustStorePassword : "trustpass"
+	dataSourceProperties : {
+	   dataSourceClassName : org.h2.jdbcx.JdbcDataSource
+	   "dataSource.url" : "jdbc:h2:"${basedir}"/persistence"
+	   "dataSource.user" : sa
+	   "dataSource.password" : ""
+	}
+	artemisAddress : "localhost:31337"
+	webAddress : "localhost:31339"
+	hostNotaryServiceLocally: false
+	extraAdvertisedServiceIds: "corda.interest_rates"
+	mapService : {
+	   hostServiceLocally : false
+	   address : "localhost:12345"
+	   identity : "Notary Service"
+	}
+	useHTTPS : false
+
+NetworkMapService plus Simple Notary configuration file.
+
+.. code-block:: text
+
+	basedir : "./nameserver"
+	myLegalName : "Notary Service"
+	nearestCity : "London"
+	keyStorePassword : "cordacadevpass"
+	trustStorePassword : "trustpass"
+	artemisAddress : "localhost:12345"
+	webAddress : "localhost:12346"
+	hostNotaryServiceLocally: true
+	extraAdvertisedServiceIds: ""
+	mapService : {
+	   hostServiceLocally : true
+	   address : ${artemisAddress}
+	   identity : ${myLegalName}
+	}
+	useHTTPS : false
+
+Configuration File Fields
+--------------------------
+
+:basedir: This specifies the node workspace folder either as an absolute path, or relative to the current working directory. It can be overidden by the ``--base-directory`` command line option, in which case the the value in the file is ignored and a ``node.conf`` file is expected in that workspace directory as the configuration source.
+
+:myLegalName: The legal identity of the node acts as a human readable alias to the node's public key and several demos use this to lookup the NodeInfo.
+
+:nearestCity: The location of the node as used to locate coordinates on the world map when running the network visualiser demo. See :doc:`visualiser`.
+
+:keyStorePassword:
+	The password to unlock the KeyStore file (``<workspace>/certificates/sslkeystore.jks``) containing the node certificate and private key.
+
+	note:: This is the non-secret value for the development certificates automatically generated during the first node run. Longer term these keys will be managed in secure hardware devices. 
+
+:trustStorePassword:
+	The password to unlock the Trust store file (``<workspace>/certificates/truststore.jks``) containing the R3 Corda root certificate. This is the non-secret value for the development certificates automatically generated during the first node run.
+
+	.. note:: Longer term these keys will be managed in secure hardware devices.
+
+:dataSourceProperties:
+    This section is used to configure the jdbc connection and database driver used for the nodes persistence. Currently the defaults in ``/node/src/main/resources/reference.conf`` are as shown in the first example. This is currently the only configuration that has been tested, although in the future full support for other storage layers will be validated.
+
+:artemisAddress:
+	The host and port on which the node is available for protocol operations over ArtemisMQ.
+
+	.. note:: In practice the ArtemisMQ messaging services bind to all local addresses on the specified port. However, note that the host is the included as the advertised entry in the NetworkMapService. As a result the value listed here must be externally accessible when running nodes across a cluster of machines.
+
+:webAddress:
+	The host and port on which the node is available for web operations.
+
+	.. note:: If HTTPS is enabled then the browser security checks will require that the accessing url host name is one of either the machine name, fully qualified machine name, or server IP address to line up with the Subject Alternative Names contained within the development certificates. This is addition to requiring the ``/config/dev/corda_dev_ca.cer`` root certificate be installed as a Trusted CA.
+	
+:hostNotaryServiceLocally: If true the Node will host and advertise a verifying Notary service.
+
+:extraAdvertisedServiceIds: A list of ServiceType id strings to be advertised to the NetworkMapService and thus be available when other nodes query the NetworkMapCache for supporting nodes. This can also include plugin services loaded from .jar files in the 
+
+:mapService.hostServiceLocally: If true the node is declaring itself as the NetworkMapService host. Otherwise the configuration below is the remote connection details for the node to connect to the NetworkMapService.
+
+:mapService.address: If the node is hosting the NetworkMapService this should be exactly equal to the artemisAddress (hence $ substitution above). Otherwise this value is the remote HostAndPort string for the ArtemisMQ service on the hosting node.
+
+:mapService.identity: If the node is hosting the NetworkMapService this should be exactly equal to the myLegalName (hence $ substitution above). Otherwise this value must match the myLegalName of the hosting node.
+
+:useHTTPS: If false the node's web server will be plain HTTP. If true the node will use the same certificate and private key from the ``<workspace>/certificates/sslkeystore.jks`` file as the ArtemisMQ port for HTTPS. If HTTPS is enabled then unencrypted HTTP traffic to the node's **webAddress** port is not supported.
+
+
+
+

docs/source/creating-a-cordapp.rst

@@ -36,11 +36,13 @@ To use an app you must also have a node server. To create a node server run the
 This will output the node JAR to ``build/libs/corda.jar`` and several sample/standard
 node setups to ``build/nodes``. For now you can use the ``build/nodes/nodea`` configuration as a template.
 
-Each node server must have a ``node.conf`` file in the same directory as the node JAR file. After first
-execution of the node server there will be many other configuration and persistence files created in this directory.
+Each node server by default must have a ``node.conf`` file in the current working directory. After first
+execution of the node server there will be many other configuration and persistence files created in a node workspace directory. This is specified as the basedir property of the node.conf file, or else can be overidden using ``--base-directory=<workspace>``.
 
 .. note:: Outside of development environments do not store your node directories in the build folder.
 
+.. warning:: Also note that the bootstrapping process of the ``corda.jar`` unpacks the Corda dependencies into a temporary folder. It is therefore suggested that the CAPSULE_CACHE_DIR environment variable be set before starting the process to control this location.
+
 Installing Apps
 ------------------
 
@@ -60,6 +62,21 @@ The plugin should automatically be registered and the configuration file used.
 
 .. warning:: If your working directory is not ``<node_dir>`` your plugins and configuration will not be used.
 
+The configuration file and workspace paths can be overidden on the command line e.g.
+
+``java -jar corda.jar --config-file=test.conf --base-directory=/opt/r3corda/nodes/test``.
+
+Otherwise the workspace folder for the node is created based upon the ``basedir`` property in the ``node.conf`` file and if this is relative it is applied relative to the current working path.
+
+Debugging your Node
+------------------
+
+To enable remote debugging of the corda process use a command line such as:
+
+``java -Dcapsule.jvm.args="-agentlib:jdwp=transport=dt_socket,server=y,suspend=y,address=5005" -jar corda.jar``
+
+This command line will start the debugger on port 5005 and pause the process awaiting debugger attachment.
+
 .. _CordaPluginRegistry: api/com.r3corda.core.node/-corda-plugin-registry/index.html
 .. _ServiceHubInternal: api/com.r3corda.node.services.api/-service-hub-internal/index.html
 .. _ServiceHub: api/com.r3corda.node.services.api/-service-hub/index.html

docs/source/index.rst

@@ -37,6 +37,7 @@ Read on to learn:
    creating-a-cordapp
    running-the-demos
    node-administration
+   corda-configuration-files
 
 .. toctree::
    :maxdepth: 2