From 214c98b6aac4a096524f31543c7390152c935805 Mon Sep 17 00:00:00 2001 From: Clinton Alexander Date: Tue, 23 Aug 2016 10:25:06 +0100 Subject: [PATCH] Added first Cordapp documentation. --- docs/source/creating-a-cordapp.rst | 65 ++++++++++++++++++++++++++++++ 1 file changed, 65 insertions(+) create mode 100644 docs/source/creating-a-cordapp.rst diff --git a/docs/source/creating-a-cordapp.rst b/docs/source/creating-a-cordapp.rst new file mode 100644 index 0000000000..c79d4560e9 --- /dev/null +++ b/docs/source/creating-a-cordapp.rst @@ -0,0 +1,65 @@ +Creating a Cordapp +================== + +A Cordapp is an application that runs on the Corda platform using Corda APIs and plugin system. Cordapps will be self +contained in separate JARs from the Corda core JAR that is created and distributed. + +Plugins +------- + +.. note:: Currently plugins are only supported via Kotlin or Java. + +To create a plugin you must extend from ``com.r3corda.core.node.CordaPluginRegistry``. The JavaDoc will contain +specific details of the implementation, but there are broadly the following extention points; + +1. Required protocols: Explicitly state which protocols are required for your plugin. +2. Service plugins: Register your services that run when Corda runs, which will be provided a ``ServiceHub``. +3. Web APIs: You may register your own endpoints under /api/ of the build in web server. +4. Static web endpoints: You may register your own static serving directories for serving web content. + +Services are used primarily for creating your own protocols, which will be the work horse of your Corda plugins. Web +APIs and serving directories will be for creating your own interface to Corda. + +Standalone Nodes +---------------- + +To use a plugin you must also have a standalone node. To create a standalone node you run: + +**Windows**:: + + gradlew.bat createStandalone + +**Other**:: + + ./gradlew createStandalone + +This will output the standalone to ``build/libs/r3prototyping-x.y-SNAPSHOT-capsule.jar`` and several sample/standard +standalone nodes to ``build/standalone``. For now you can use the ``build/standalone/nodea`` directory as a template or +example. + +Each standalone node must contain a ``node.conf`` file in the same directory as the standalone JAR file. After first +execution of the standalone node there will be many other configuration and persistence files created in this directory. + +.. warning:: Deleting your standalone node directory in any way, including ``gradle clean`` will delete all persistence. + +.. note:: Outside of development environments do not store your standalone node in the build folder. + +Installing Plugins +------------------ + +Once you have created your distribution JAR you can install it to a node by adding it to ``/plugins/``. In this +case the ``node_dir`` is the location where your standalone node's JAR and configuration file is. + +.. note:: If the plugins directory does not exist you can create it manually. + +Starting your Node +------------------ + +Now you have a standalone node with your Cordapp installed, you can run it by navigating to ```` and running + + java -jar r3prototyping-x.y-SNAPSHOT-capsule.jar + +The plugin should automatically be registered and the configuration file used. + +.. warning:: If your working directory is not ```` your plugins and configuration will not be used. +