Updates the example CorDapp page.

docs/source/building-against-master.rst

@@ -0,0 +1,34 @@
+Building against Master
+=======================
+
+When developing a CorDapp, it is advisable to use the most recent Corda Milestone release, which has been extensively
+tested. However, if you need to use a very recent feature of the codebase, you may need to work against the unstable
+Master branch.
+
+To work against the Master branch, proceed as follows:
+
+* Open a terminal window in the folder where you cloned the Corda repository
+  (available `here <https://github.com/corda/corda>`_)
+
+* Use the following command to check out the latest master branch:
+
+    ``git fetch; git checkout master``
+
+* Publish Corda to your local Maven repository using the following commands:
+
+  * Unix/Mac OSX: ``./gradlew install``
+  * Windows: ``gradlew.bat install``
+
+  By default, the Maven local repository is found at:
+
+  * ``~/.m2/repository`` on Unix/Mac OS X
+  * ``%HOMEPATH%\.m2`` on Windows
+
+  This step is not necessary when using a Milestone releases, as the Milestone releases are published online
+
+.. warning:: If you do modify your local Corda repository after having published it to Maven local, then you must
+   re-publish it to Maven local for the local installation to reflect the changes you have made.
+
+.. warning:: As the Corda repository evolves on a daily basis, two clones of the Master branch at different points in
+   time may differ. If you are using a Master release and need help debugging an error, then please let us know the
+   **commit** you are working from. This will help us ascertain the issue.

docs/source/corda-nodes-index.rst

@@ -4,9 +4,11 @@ Corda nodes
 .. toctree::
    :maxdepth: 1
 
+   deploying-a-node
    running-a-node
    clientrpc
    shell
+   node-database
    node-administration
    corda-configuration-file
    out-of-process-verification

docs/source/deploying-a-node.rst

@@ -0,0 +1,125 @@
+Deploying a node
+================
+
+Building nodes using Gradle
+---------------------------
+Nodes are usually built using a Gradle task. The canonical Gradle file for building nodes is the one used by the
+CorDapp template. Both a `Java version <https://github.com/corda/cordapp-template-java/blob/master/build.gradle>`_ and
+a `Kotlin version <https://github.com/corda/cordapp-template-kotlin/blob/master/build.gradle>`_ are available.
+
+The buildscript
+~~~~~~~~~~~~~~~
+The buildscript is always located at the top of the build file. Among other things, this section determines which
+version of Corda and the Corda gradle plugins are used to build the nodes and their CorDapps:
+
+.. sourcecode:: groovy
+
+    ext.corda_release_version = '0.14-SNAPSHOT'
+    ext.corda_gradle_plugins_version = '0.14.2'
+
+Release versions suffixed by ``-SNAPSHOT`` are based on the unstable Master branch
+(see :doc:`building-against-master`). You should generally use the latest Milestone release instead.
+
+``corda_gradle_plugins_versions`` are given in the form ``major.minor.patch``. You should use the same ``major`` and
+``minor`` versions as the Corda version you are using, and the latest ``patch`` version. A list of all the available
+versions can be found here: https://bintray.com/r3/corda/cordformation.
+
+Project dependencies
+~~~~~~~~~~~~~~~~~~~~
+If your CorDapps have any additional external dependencies, they should be added to the ``dependencies`` section:`
+
+.. sourcecode:: groovy
+
+  dependencies {
+
+      ...
+
+      // Cordapp dependencies
+      // Specify your cordapp's dependencies below, including dependent cordapps
+  }
+
+For further information about managing dependencies, see
+`the Gradle docs <https://docs.gradle.org/current/userguide/dependency_management.html>`_.
+
+Building the nodes
+~~~~~~~~~~~~~~~~~~
+Cordform is the local node deployment system for CorDapps. The nodes generated are intended for experimenting,
+debugging, and testing node configurations, but not for production or testnet deployment.
+
+Here is an example Gradle task called ``deployNodes`` that uses the Cordform plugin to deploy three nodes, plus a
+notary/network map node:
+
+.. sourcecode:: groovy
+
+    task deployNodes(type: net.corda.plugins.Cordform, dependsOn: ['jar']) {
+        directory "./build/nodes"
+        networkMap "CN=Controller,O=R3,OU=corda,L=London,C=UK"
+        node {
+            name "CN=Controller,O=R3,OU=corda,L=London,C=UK"
+            advertisedServices = ["corda.notary.validating"]
+            p2pPort 10002
+            rpcPort 10003
+            webPort 10004
+            cordapps = []
+        }
+        node {
+            name "CN=NodeA,O=NodeA,L=London,C=UK"
+            advertisedServices = []
+            p2pPort 10005
+            rpcPort 10006
+            webPort 10007
+            cordapps = []
+            rpcUsers = [[ user: "user1", "password": "test", "permissions": []]]
+        }
+        node {
+            name "CN=NodeB,O=NodeB,L=New York,C=US"
+            advertisedServices = []
+            p2pPort 10008
+            rpcPort 10009
+            webPort 10010
+            cordapps = []
+            rpcUsers = [[ user: "user1", "password": "test", "permissions": []]]
+        }
+        node {
+            name "CN=NodeC,O=NodeC,L=Paris,C=FR"
+            advertisedServices = []
+            p2pPort 10011
+            rpcPort 10012
+            webPort 10013
+            cordapps = []
+            rpcUsers = [[ user: "user1", "password": "test", "permissions": []]]
+        }
+    }
+
+You can extend ``deployNodes`` to generate any number of nodes you like. The only requirement is that you must specify
+one node as running the network map service, by putting their name in the ``networkMap`` field. In our example, the
+``Controller`` is set as the network map service.
+
+.. warning:: When adding nodes, make sure that there are no port clashes!
+
+Any CorDapps defined in the project's source folders are also automatically registered with all the nodes defined in
+``deployNodes``, even if the CorDapps are not listed in each node's ``cordapps`` entry.
+
+Deploying your nodes
+--------------------
+You deploy a set of nodes by running your ``build.gradle`` file's Cordform task. For example, if we were using the
+standard ``deployNodes`` task defined above, we'd create our nodes by running the following commands in a terminal
+window from the root of the project:
+
+* Unix/Mac OSX: ``./gradlew deployNodes``
+* Windows: ``gradlew.bat deployNodes``
+
+After the build process has finished, you will find the newly-built nodes under ``kotlin-source/build/nodes``. There
+will be one folder generated for each node you built, plus a ``runnodes`` shell script (or batch file on Windows) to
+run all the nodes at once. Each node in the ``nodes`` folder has the following structure:
+
+.. sourcecode:: none
+
+    . nodeName
+    ├── corda.jar       // The Corda runtime
+    ├── node.conf       // The node's configuration
+    └── plugins         // Any installed CorDapps
+
+.. note:: Outside of development environments, do not store your node directories in the build folder.
+
+If you make any changes to your ``deployNodes`` task, you will need to re-run the task to see the changes take effect.

docs/source/getting-set-up.rst

@@ -158,11 +158,14 @@ instead by running ``git checkout release-M12``.
 
 Next steps
 ----------
+The best way to check that everything is working fine is by running the :doc:`tutorial CorDapp <tutorial-cordapp>` and
+the :doc:`samples <running-the-demos>`.
 
-The best way to check that everything is working fine is by :doc:`running-the-demos`.
+Next, you should read through :doc:`Corda Key Concepts <key-concepts>` to understand how Corda works.
 
-Once you have these demos running, you may be interested in writing your own CorDapps, in which case you should refer to 
+By then, you'll be ready to start writing your own CorDapps. Learn how to do this in the
-:doc:`tutorial-cordapp`.
+:doc:`Hello, World tutorial <hello-world-index>`. You may want to refer to the :doc:`API docs <api-index>` along the
+way.
 
 If you encounter any issues, please see the :doc:`troubleshooting` page, or get in touch with us on the
 `forums <https://discourse.corda.net/>`_ or via `slack <http://slack.corda.net/>`_.

docs/source/node-database.rst

@@ -0,0 +1,28 @@
+Node database
+=============
+
+Currently, nodes store their data in an H2 database. In the future, we plan to support a wide range of databases.
+
+You can connect directly to a running node's database to see its stored states, transactions and attachments as
+follows:
+
+* Download the `h2 platform-independent zip <http://www.h2database.com/html/download.html>`_, unzip the zip, and
+  navigate in a terminal window to the unzipped folder
+* Change directories to the bin folder:
+
+  ``cd h2/bin``
+
+* Run the following command to open the h2 web console in a web browser tab:
+
+  * Unix: ``sh h2.sh``
+  * Windows: ``h2.bat``
+
+* Find the node's JDBC connection string. Each node outputs its connection string in the terminal
+  window as it starts up. In a terminal window where a node is running, look for the following string:
+
+  ``Database connection URL is              : jdbc:h2:tcp://10.18.0.150:56736/node``
+
+* Paste this string into the JDBC URL field and click ``Connect``, using the default username and password.
+
+You will be presented with a web interface that shows the contents of your node's storage and vault, and provides an
+interface for you to query them using SQL.

docs/source/quickstart-index.rst

@@ -7,4 +7,5 @@ Quickstart
    getting-set-up
    tutorial-cordapp
    running-the-demos
+   building-against-master
    CLI-vs-IDE

docs/source/running-a-node.rst

@@ -1,38 +1,20 @@
 Running a node
 ==============
 
-Deploying your node
--------------------
-
-You deploy a node by running the ``gradle deployNodes`` task. 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 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 this
-workspace directory. The directory can be overridden by the ``--base-directory=<workspace>`` command line argument.
-
-.. 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.
-
 Starting your node
 ------------------
 
-Now you have a node server with your app installed, you can run it by navigating to ``<node_dir>`` and running:
+After following the steps in :doc:`deploying-a-node`, you should have deployed your node(s) with any chosen CorDapps
+installed. You run each node by navigating to ``<node_dir>`` in a terminal window and running:
 
 .. code-block:: shell
 
    Windows:   java -jar corda.jar
    UNIX:      ./corda.jar
 
-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.
+The configuration file and workspace paths can be overridden on the command line. For example:
 
 ``./corda.jar --config-file=test.conf --base-directory=/opt/r3corda/nodes/test``.
 
@@ -41,14 +23,14 @@ Otherwise the workspace folder for the node is the current working path.
 Debugging your node
 -------------------
 
-To enable remote debugging of the corda process use a command line such as:
+To enable remote debugging of the node, run the following from the terminal window:
 
 ``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.
 
-Viewing persisted state of your node
+Viewing the persisted state of your node
-------------------------------------
+----------------------------------------
 
 To make examining the persisted contract states of your node or the internal node database tables easier, and providing you are
 using the default database configuration used for demos, you should be able to connect to the internal node database over
@@ -61,140 +43,4 @@ at the present time, and should certainly be treated as read-only.
 
 .. _CordaPluginRegistry: api/kotlin/corda/net.corda.core.node/-corda-plugin-registry/index.html
 .. _PluginServiceHub: api/kotlin/corda/net.corda.core.node/-plugin-service-hub/index.html
-.. _ServiceHub: api/kotlin/corda/net.corda.core.node/-service-hub/index.html
+.. _ServiceHub: api/kotlin/corda/net.corda.core.node/-service-hub/index.html
-
-Building against Corda
-----------------------
-
-To publish to your local Maven repository (in ``~/.m2`` on Unix and ``%HOMEPATH%\.m2`` on Windows) run the following
-in the root directory of the Corda code:
-
-.. code-block:: shell
-
-    ./gradlew install
-
-This will publish corda-$version.jar, finance-$version.jar, core-$version.jar and node-$version.jar to the
-group net.corda. You can now depend on these as you normally would a Maven dependency, using the group id
-``net.corda``.
-
-There are several Gradle plugins that reduce your build.gradle boilerplate and make development of CorDapps easier.
-The available plugins are in the gradle-plugins directory of the Corda repository.
-
-To install to your local Maven repository the plugins that CorDapp gradle files require, enter the ``gradle-plugins``
-directory and then run ``../gradle install``. The plugins will now be installed to your local Maven repository.
-
-Using Gradle plugins
-~~~~~~~~~~~~~~~~~~~~
-
-To use the plugins, if you are not already using the CorDapp template project, you must modify your build.gradle. Add
-the following segments to the relevant part of your build.gradle.
-
-.. code-block:: groovy
-
-    buildscript {
-        ext.corda_release_version = '<enter the corda version you build against here>'
-        ext.corda_gradle_plugins_version = '<enter the gradle plugins version here>' // This is usually the same as corda_release_version.
-        ... your buildscript ...
-
-        repositories {
-            ... other repositories ...
-            mavenLocal()
-        }
-
-        dependencies {
-            ... your dependencies ...
-            classpath "net.corda.plugins:cordformation:$corda_gradle_plugins_version"
-            classpath "net.corda.plugins:quasar-utils:$corda_gradle_plugins_version"
-            classpath "net.corda.plugins:publish-utils:$corda_gradle_plugins_version"
-        }
-    }
-
-    apply plugin: 'net.corda.plugins.cordformation'
-    apply plugin: 'net.corda.plugins.quasar-utils'
-    apply plugin: 'net.corda.plugins.publish-utils'
-
-    repositories {
-        mavenLocal()
-        ... other repositories here ...
-    }
-
-    dependencies {
-        compile "net.corda.core:$corda_release_version"
-        compile "net.corda.finance:$corda_release_version"
-        compile "net.corda.node:$corda_release_version"
-        compile "net.corda.corda:$corda_release_version"
-        ... other dependencies here ...
-    }
-
-    ... your tasks ...
-
-    // Standard way to publish CorDapps to maven local with the maven-publish and publish-utils plugin.
-    publishing {
-        publications {
-            jarAndSources(MavenPublication) {
-                from components.java
-                // The two lines below are the tasks added by this plugin.
-                artifact sourceJar
-                artifact javadocJar
-            }
-        }
-    }
-
-
-
-Cordformation
-~~~~~~~~~~~~~
-
-Cordformation is the local node deployment system for CorDapps, the nodes generated are intended to be used for
-experimenting, debugging, and testing node configurations and setups but not intended for production or testnet
-deployment.
-
-To use this gradle plugin you must add a new task that is of the type ``net.corda.plugins.Cordform`` to your
-build.gradle and then configure the nodes you wish to deploy with the Node and nodes configuration DSL.
-This DSL is specified in the `JavaDoc <api/javadoc/>`_. An example of this is in the CorDapp template and
-below
-is a three node example;
-
-.. code-block:: text
-
-    task deployNodes(type: net.corda.plugins.Cordform, dependsOn: ['jar']) {
-        directory "./build/nodes" // The output directory
-        networkMap "CN=Controller,O=R3,OU=corda,L=London,C=GB" // The distinguished name of the node named here will be used as the networkMapService.address on all other nodes.
-        node {
-            name "CN=Controller,O=R3,OU=corda,L=London,C=GB"
-            advertisedServices = [ "corda.notary.validating" ]
-            p2pPort 10002
-            rpcPort 10003
-            webPort 10004
-            h2Port 11002
-            cordapps []
-        }
-        node {
-            name "CN=NodeA,O=R3,OU=corda,L=London,C=GB"
-            advertisedServices = []
-            p2pPort 10005
-            rpcPort 10006
-            webPort 10007
-            h2Port 11005
-            cordapps []
-        }
-        node {
-            name "CN=NodeB,O=R3,OU=corda,L=New York,C=US"
-            advertisedServices = []
-            p2pPort 10008
-            rpcPort 10009
-            webPort 10010
-            h2Port 11008
-            cordapps []
-        }
-    }
-
-You can create more configurations with new tasks that extend Cordform.
-
-New nodes can be added by simply adding another node block and giving it a different name, directory and ports. When you
-run this task it will install the nodes to the directory specified and a script will be generated to run the nodes with
-one command (``runnodes``). On MacOS X this script will run each node in a new terminal tab, and on Linux it will open
-up a new XTerm for each node. On Windows the (``runnodes.bat``) script will run one node per window.
-
-Other CorDapps can also be specified if they are already specified as classpath or compile dependencies in your
-``build.gradle``.