mirror of
https://github.com/corda/corda.git
synced 2025-04-11 13:21:26 +00:00
Updates the example CorDapp page.
This commit is contained in:
Joel Dudley
GitHub
parent
6f7794ac93
commit
bb4501c09c
34
docs/source/building-against-master.rst
Normal file
34
docs/source/building-against-master.rst
Normal file
@ -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.
|
||||
@ -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
|
||||
125
docs/source/deploying-a-node.rst
Normal file
125
docs/source/deploying-a-node.rst
Normal file
@ -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.
|
||||
@ -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
|
||||
:doc:`tutorial-cordapp`.
|
||||
By then, you'll be ready to start writing your own CorDapps. Learn how to do this in the
|
||||
: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/>`_.
|
||||
|
||||
28
docs/source/node-database.rst
Normal file
28
docs/source/node-database.rst
Normal file
@ -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.
|
||||
@ -7,4 +7,5 @@ Quickstart
|
||||
getting-set-up
|
||||
tutorial-cordapp
|
||||
running-the-demos
|
||||
building-against-master
|
||||
CLI-vs-IDE
|
||||
@ -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
|
||||
|
||||
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``.
|
||||
.. _ServiceHub: api/kotlin/corda/net.corda.core.node/-service-hub/index.html
|
||||
File diff suppressed because it is too large
Load Diff
Loading…
x
Reference in New Issue
Block a user