mirror of
https://github.com/corda/corda.git
synced 2024-12-20 05:28:21 +00:00
Backports changes to docs on generating and running nodes.
This commit is contained in:
Joel Dudley
GitHub
parent
139c15faec
commit
a94ca991cd
@ -124,12 +124,12 @@ path to the node's base directory.
|
||||
:rpcUsers: A list of users who are authorised to access the RPC system. Each user in the list is a config object with the
|
||||
following fields:
|
||||
|
||||
:username: Username consisting only of word characters (a-z, A-Z, 0-9 and _)
|
||||
:password: The password
|
||||
:permissions: A list of permission strings which RPC methods can use to control access
|
||||
|
||||
If this field is absent or an empty list then RPC is effectively locked down. Alternatively, if it contains the string
|
||||
``ALL`` then the user is permitted to use *any* RPC method. This value is intended for administrator users and for developers.
|
||||
:username: Username consisting only of word characters (a-z, A-Z, 0-9 and _)
|
||||
:password: The password
|
||||
:permissions: A list of permissions for starting flows via RPC. To give the user the permission to start the flow
|
||||
``foo.bar.FlowClass``, add the string ``StartFlow.foo.bar.FlowClass`` to the list. If the list
|
||||
contains the string ``ALL``, the user can start any flow via RPC. This value is intended for administrator
|
||||
users and for development.
|
||||
|
||||
:devMode: This flag sets the node to run in development mode. On startup, if the keystore ``<workspace>/certificates/sslkeystore.jks``
|
||||
does not exist, a developer keystore will be used if ``devMode`` is true. The node will exit if ``devMode`` is false
|
||||
@ -141,4 +141,4 @@ path to the node's base directory.
|
||||
interfaces, and then by sending an IP discovery request to the network map service. Set to ``false`` to disable.
|
||||
|
||||
:certificateSigningService: Certificate Signing Server address. It is used by the certificate signing request utility to
|
||||
obtain SSL certificate. (See :doc:`permissioning` for more information.)
|
||||
obtain SSL certificate (see :doc:`permissioning` for more information)
|
||||
@ -4,8 +4,9 @@ Corda nodes
|
||||
.. toctree::
|
||||
:maxdepth: 1
|
||||
|
||||
deploying-a-node
|
||||
generating-a-node
|
||||
running-a-node
|
||||
deploying-a-node
|
||||
corda-configuration-file
|
||||
clientrpc
|
||||
shell
|
||||
|
||||
@ -118,9 +118,9 @@ Creating the CorDapp JAR
|
||||
The gradle ``jar`` task included in the CorDapp template build file will automatically build your CorDapp JAR correctly
|
||||
as long as your dependencies are set correctly.
|
||||
|
||||
Note that the hash of the resulting CorDapp JAR is not deterministic, as it depends on variables such as the timestamp
|
||||
at creation. Nodes running the same CorDapp must therefore ensure they are using the exact same CorDapp jar, and not
|
||||
different versions of the JAR created from identical sources.
|
||||
.. warning:: The hash of the generated CorDapp JAR is not deterministic, as it depends on variables such as the
|
||||
timestamp at creation. Nodes running the same CorDapp must therefore ensure they are using the exact same CorDapp
|
||||
jar, and not different versions of the JAR created from identical sources.
|
||||
|
||||
The filename of the JAR must include a unique identifier to deduplicate it from other releases of the same CorDapp.
|
||||
This is typically done by appending the version string to the CorDapp's name. This unique identifier should not change
|
||||
@ -131,7 +131,7 @@ Installing the CorDapp jar
|
||||
--------------------------
|
||||
|
||||
.. note:: Before installing a CorDapp, you must create one or more nodes to install it on. For instructions, please see
|
||||
:doc:`deploying-a-node`.
|
||||
:doc:`generating-a-node`.
|
||||
|
||||
At runtime, nodes will load any plugins present in their ``plugins`` folder. Therefore in order to install a CorDapp on
|
||||
a node, the CorDapp JAR must be added to the ``<node_dir>/plugins/`` folder, where ``node_dir`` is the folder in which
|
||||
|
||||
@ -1,140 +1,295 @@
|
||||
Deploying a node
|
||||
================
|
||||
|
||||
Node structure
|
||||
--------------
|
||||
Each Corda node has the following structure:
|
||||
.. contents::
|
||||
|
||||
.. sourcecode:: none
|
||||
.. note:: These instructions are intended for people who want to deploy a Corda node to a server,
|
||||
whether they have developed and tested a CorDapp following the instructions in :doc:`generating-a-node`
|
||||
or are deploying a third-party CorDapp.
|
||||
|
||||
.
|
||||
├── certificates // The node's doorman certificates
|
||||
├── corda-webserver.jar // The built-in node webserver
|
||||
├── corda.jar // The core Corda libraries
|
||||
├── logs // The node logs
|
||||
├── node.conf // The node's configuration files
|
||||
├── persistence.mv.db // The node's database
|
||||
└── plugins // The CorDapps jars installed on the node
|
||||
Linux: Installing and running Corda as a system service
|
||||
-------------------------------------------------------
|
||||
We recommend creating system services to run a node and the optional webserver. This provides logging and service
|
||||
handling, and ensures the Corda service is run at boot.
|
||||
|
||||
The node is configured by editing its ``node.conf`` file. You install CorDapps on the node by dropping the CorDapp JARs
|
||||
into the ``plugins`` folder.
|
||||
**Prerequisites**:
|
||||
|
||||
Node naming
|
||||
-----------
|
||||
A node's name must be a valid X500 name that obeys the following additional constraints:
|
||||
* Oracle Java 8. The supported versions are listed in :doc:`getting-set-up`
|
||||
|
||||
* The fields of the name have the following maximum character lengths:
|
||||
1. Add a system user which will be used to run Corda:
|
||||
|
||||
* Common name: 64
|
||||
* Organisation: 128
|
||||
* Organisation unit: 64
|
||||
* Locality: 64
|
||||
* State: 64
|
||||
``sudo adduser --system --no-create-home --group corda``
|
||||
|
||||
* The country code is a valid ISO 3166-1 two letter code in upper-case
|
||||
2. Create a directory called ``/opt/corda`` and change its ownership to the user you want to use to run Corda:
|
||||
|
||||
* The organisation, locality and country attributes are present
|
||||
``mkdir /opt/corda; chown corda:corda /opt/corda``
|
||||
|
||||
* The organisation field of the name obeys the following constraints:
|
||||
3. Download the `Corda jar <https://r3.bintray.com/corda/net/corda/corda/>`_
|
||||
(under ``/VERSION_NUMBER/corda-VERSION_NUMBER.jar``) and place it in ``/opt/corda``
|
||||
|
||||
* Has at least two letters
|
||||
* No leading or trailing whitespace
|
||||
* No double-spacing
|
||||
* Upper-case first letter
|
||||
* Does not contain the words "node" or "server"
|
||||
* Does not include the characters ',' or '=' or '$' or '"' or '\'' or '\\'
|
||||
* Is in NFKC normalization form
|
||||
* Only the latin, common and inherited unicode scripts are supported
|
||||
4. (Optional) Download the `Corda webserver jar <http://r3.bintray.com/corda/net/corda/corda-webserver/>`_
|
||||
(under ``/VERSION_NUMBER/corda-VERSION_NUMBER.jar``) and place it in ``/opt/corda``
|
||||
|
||||
The deployNodes task
|
||||
--------------------
|
||||
The CorDapp template defines a ``deployNodes`` task that allows you to automatically generate and configure a set of
|
||||
nodes:
|
||||
5. Create a directory called ``plugins`` in ``/opt/corda`` and save your CorDapp jar file to it. Alternatively, download one of
|
||||
our `sample CorDapps <https://www.corda.net/samples/>`_ to the ``plugins`` directory
|
||||
|
||||
.. sourcecode:: groovy
|
||||
6. Save the below as ``/opt/corda/node.conf``. See :doc:`corda-configuration-file` for a description of these options
|
||||
|
||||
task deployNodes(type: net.corda.plugins.Cordform, dependsOn: ['jar']) {
|
||||
directory "./build/nodes"
|
||||
networkMap "O=Controller,L=London,C=GB"
|
||||
node {
|
||||
name "O=Controller,L=London,C=GB"
|
||||
// The notary will offer a validating notary service.
|
||||
// Set to `corda.notary.simple` for a non-validating notary.
|
||||
advertisedServices = ["corda.notary.validating"]
|
||||
p2pPort 10002
|
||||
rpcPort 10003
|
||||
// No webport property, so no webserver will be created.
|
||||
h2Port 10004
|
||||
sshdPort 22
|
||||
// Includes the corda-finance CorDapp on our node.
|
||||
cordapps = ["net.corda:corda-finance:$corda_release_version"]
|
||||
.. code-block:: json
|
||||
|
||||
basedir : "/opt/corda"
|
||||
p2pAddress : "example.com:10002"
|
||||
rpcAddress : "example.com:10003"
|
||||
webAddress : "0.0.0.0:10004"
|
||||
h2port : 11000
|
||||
emailAddress : "you@example.com"
|
||||
myLegalName : "O=Bank of Breakfast Tea, L=London, C=GB"
|
||||
keyStorePassword : "cordacadevpass"
|
||||
trustStorePassword : "trustpass"
|
||||
useHTTPS : false
|
||||
devMode : false
|
||||
networkMapService {
|
||||
address="networkmap.foo.bar.com:10002"
|
||||
legalName="O=FooBar NetworkMap, L=Dublin, C=IE"
|
||||
}
|
||||
rpcUsers=[
|
||||
{
|
||||
user=corda
|
||||
password=portal_password
|
||||
permissions=[
|
||||
ALL
|
||||
]
|
||||
}
|
||||
]
|
||||
|
||||
7. Make the following changes to ``/opt/corda/node.conf``:
|
||||
|
||||
* Change the ``p2pAddress`` and ``rpcAddress`` values to start with your server's hostname or external IP address.
|
||||
This is the address other nodes or RPC interfaces will use to communicate with your node
|
||||
* Change the ports if necessary, for example if you are running multiple nodes on one server (see below)
|
||||
* Enter an email address which will be used as an administrative contact during the registration process. This is
|
||||
only visible to the permissioning service
|
||||
* Enter your node's desired legal name. This will be used during the issuance of your certificate and should rarely
|
||||
change as it should represent the legal identity of your node
|
||||
|
||||
* Organization (``O=``) should be a unique and meaningful identifier (e.g. Bank of Breakfast Tea)
|
||||
* Location (``L=``) is your nearest city
|
||||
* Country (``C=``) is the `ISO 3166-1 alpha-2 code <https://en.wikipedia.org/wiki/ISO_3166-1_alpha-2>`_
|
||||
* Change the RPC username and password
|
||||
|
||||
.. note:: Ubuntu 16.04 and most current Linux distributions use SystemD, so if you are running one of these
|
||||
distributions follow the steps marked **SystemD**. If you are running Ubuntu 14.04, follow the instructions
|
||||
for **Upstart**.
|
||||
|
||||
8. **SystemD**: Create a ``corda.service`` file based on the example below and save it in the ``/etc/systemd/system/``
|
||||
directory
|
||||
|
||||
.. code-block:: shell
|
||||
|
||||
[Unit]
|
||||
Description=Corda Node - Bank of Breakfast Tea
|
||||
Requires=network.target
|
||||
|
||||
[Service]
|
||||
Type=simple
|
||||
User=corda
|
||||
WorkingDirectory=/opt/corda
|
||||
ExecStart=/usr/bin/java -Xmx2048m -jar /opt/corda/corda.jar
|
||||
Restart=on-failure
|
||||
|
||||
[Install]
|
||||
WantedBy=multi-user.target
|
||||
|
||||
8. **Upstart**: Create a ``corda.conf`` file based on the example below and save it in the ``/etc/init/`` directory
|
||||
|
||||
.. code-block:: shell
|
||||
|
||||
description "Corda Node - Bank of Breakfast Tea"
|
||||
|
||||
start on runlevel [2345]
|
||||
stop on runlevel [!2345]
|
||||
|
||||
respawn
|
||||
setuid corda
|
||||
chdir /opt/corda
|
||||
exec java -Xmx2048m -jar /opt/corda/corda.jar
|
||||
|
||||
9. Make the following changes to ``corda.service`` or ``corda.conf``:
|
||||
|
||||
* Make sure the service description is informative - particularly if you plan to run multiple nodes.
|
||||
* Change the username to the user account you want to use to run Corda. **We recommend that this user account is
|
||||
not root**
|
||||
* Set the maximum amount of memory available to the Corda process by changing the ``-Xmx2048m`` parameter
|
||||
* **SystemD**: Make sure the ``corda.service`` file is owned by root with the correct permissions:
|
||||
|
||||
* ``sudo chown root:root /etc/systemd/system/corda.service``
|
||||
* ``sudo chmod 644 /etc/systemd/system/corda.service``
|
||||
|
||||
* **Upstart**: Make sure the ``corda.conf`` file is owned by root with the correct permissions:
|
||||
|
||||
* ``sudo chown root:root /etc/init/corda.conf``
|
||||
* ``sudo chmod 644 /etc/init/corda.conf``
|
||||
|
||||
.. note:: The Corda webserver provides a simple interface for interacting with your installed CorDapps in a browser.
|
||||
Running the webserver is optional.
|
||||
|
||||
10. **SystemD**: Create a ``corda-webserver.service`` file based on the example below and save it in the ``/etc/systemd/system/``
|
||||
directory
|
||||
|
||||
.. code-block:: shell
|
||||
|
||||
[Unit]
|
||||
Description=Webserver for Corda Node - Bank of Breakfast Tea
|
||||
Requires=network.target
|
||||
|
||||
[Service]
|
||||
Type=simple
|
||||
User=corda
|
||||
WorkingDirectory=/opt/corda
|
||||
ExecStart=/usr/bin/java -jar /opt/corda/corda-webserver.jar
|
||||
Restart=on-failure
|
||||
|
||||
[Install]
|
||||
WantedBy=multi-user.target
|
||||
|
||||
10. **Upstart**: Create a ``corda-webserver.conf`` file based on the example below and save it in the ``/etc/init/``
|
||||
directory
|
||||
|
||||
.. code-block:: shell
|
||||
|
||||
description "Webserver for Corda Node - Bank of Breakfast Tea"
|
||||
|
||||
start on runlevel [2345]
|
||||
stop on runlevel [!2345]
|
||||
|
||||
respawn
|
||||
setuid corda
|
||||
chdir /opt/corda
|
||||
exec java -jar /opt/corda/corda-webserver.jar
|
||||
|
||||
11. Provision the required certificates to your node. Contact the network permissioning service or see
|
||||
:doc:`permissioning`
|
||||
|
||||
12. **SystemD**: You can now start a node and its webserver and set the services to start on boot by running the
|
||||
following ``systemctl`` commands:
|
||||
|
||||
* ``sudo systemctl daemon-reload``
|
||||
* ``sudo systemctl enable --now corda``
|
||||
* ``sudo systemctl enable --now corda-webserver``
|
||||
|
||||
12. **Upstart**: You can now start a node and its webserver by running the following commands:
|
||||
|
||||
* ``sudo start corda``
|
||||
* ``sudo start corda-webserver``
|
||||
|
||||
The Upstart configuration files created above tell Upstart to start the Corda services on boot so there is no need to explicitly enable them.
|
||||
|
||||
You can run multiple nodes by creating multiple directories and Corda services, modifying the ``node.conf`` and
|
||||
SystemD or Upstart configuration files so they are unique.
|
||||
|
||||
Windows: Installing and running Corda as a Windows service
|
||||
----------------------------------------------------------
|
||||
We recommend running Corda as a Windows service. This provides service handling, ensures the Corda service is run
|
||||
at boot, and means the Corda service stays running with no users connected to the server.
|
||||
|
||||
**Prerequisites**:
|
||||
|
||||
* Oracle Java 8. The supported versions are listed in :doc:`getting-set-up`
|
||||
|
||||
1. Create a Corda directory and download the Corda jar. Replace ``VERSION_NUMBER`` with the desired version. Here's an
|
||||
example using PowerShell:
|
||||
|
||||
.. code-block:: PowerShell
|
||||
|
||||
mkdir C:\Corda
|
||||
wget http://jcenter.bintray.com/net/corda/corda/VERSION_NUMBER/corda-VERSION_NUMBER.jar -OutFile C:\Corda\corda.jar
|
||||
|
||||
2. Create a directory called ``plugins`` in ``/opt/corda`` and save your CorDapp jar file to it. Alternatively,
|
||||
download one of our `sample CorDapps <https://www.corda.net/samples/>`_ to the ``plugins`` directory
|
||||
|
||||
3. Save the below as ``C:\Corda\node.conf``. See :doc:`corda-configuration-file` for a description of these options
|
||||
|
||||
.. code-block:: json
|
||||
|
||||
basedir : "C:\\Corda"
|
||||
p2pAddress : "example.com:10002"
|
||||
rpcAddress : "example.com:10003"
|
||||
webAddress : "0.0.0.0:10004"
|
||||
h2port : 11000
|
||||
emailAddress: "you@example.com"
|
||||
myLegalName : "O=Bank of Breakfast Tea, L=London, C=GB"
|
||||
keyStorePassword : "cordacadevpass"
|
||||
trustStorePassword : "trustpass"
|
||||
extraAdvertisedServiceIds: [ "" ]
|
||||
useHTTPS : false
|
||||
devMode : false
|
||||
networkMapService {
|
||||
address="networkmap.foo.bar.com:10002"
|
||||
legalName="O=FooBar NetworkMap, L=Dublin, C=IE"
|
||||
}
|
||||
node {
|
||||
name "O=PartyA,L=London,C=GB"
|
||||
advertisedServices = []
|
||||
p2pPort 10005
|
||||
rpcPort 10006
|
||||
webPort 10007
|
||||
h2Port 10008
|
||||
sshdPort 22
|
||||
cordapps = ["net.corda:corda-finance:$corda_release_version"]
|
||||
// Grants user1 all RPC permissions.
|
||||
rpcUsers = [[ user: "user1", "password": "test", "permissions": ["ALL"]]]
|
||||
}
|
||||
node {
|
||||
name "O=PartyB,L=New York,C=US"
|
||||
advertisedServices = []
|
||||
p2pPort 10009
|
||||
rpcPort 10010
|
||||
webPort 10011
|
||||
h2Port 10012
|
||||
sshdPort 22
|
||||
cordapps = ["net.corda:corda-finance:$corda_release_version"]
|
||||
// Grants user1 the ability to start the MyFlow flow.
|
||||
rpcUsers = [[ user: "user1", "password": "test", "permissions": ["StartFlow.net.corda.flows.MyFlow"]]]
|
||||
}
|
||||
}
|
||||
rpcUsers=[
|
||||
{
|
||||
user=corda
|
||||
password=portal_password
|
||||
permissions=[
|
||||
ALL
|
||||
]
|
||||
}
|
||||
]
|
||||
|
||||
Running this task will create three nodes in the ``build/nodes`` folder:
|
||||
4. Make the following changes to ``C:\Corda\node.conf``:
|
||||
|
||||
* A ``Controller`` node that:
|
||||
* Change the ``p2pAddress`` and ``rpcAddress`` values to start with your server's hostname or external IP address.
|
||||
This is the address other nodes or RPC interfaces will use to communicate with your node
|
||||
* Change the ports if necessary, for example if you are running multiple nodes on one server (see below)
|
||||
* Enter an email address which will be used as an administrative contact during the registration process. This is
|
||||
only visible to the permissioning service
|
||||
* Enter your node's desired legal name. This will be used during the issuance of your certificate and should rarely
|
||||
change as it should represent the legal identity of your node
|
||||
|
||||
* Serves as the network map
|
||||
* Offers a validating notary service
|
||||
* Will not have a webserver (since ``webPort`` is not defined)
|
||||
* Is running the ``corda-finance`` CorDapp
|
||||
* Organization (``O=``) should be a unique and meaningful identifier (e.g. Bank of Breakfast Tea)
|
||||
* Location (``L=``) is your nearest city
|
||||
* Country (``C=``) is the `ISO 3166-1 alpha-2 code <https://en.wikipedia.org/wiki/ISO_3166-1_alpha-2>`_
|
||||
* Change the RPC username and password
|
||||
|
||||
* ``PartyA`` and ``PartyB`` nodes that:
|
||||
5. Copy the required Java keystores to the node. See :doc:`permissioning`
|
||||
|
||||
* Are pointing at the ``Controller`` as the network map service
|
||||
* Are not offering any services
|
||||
* Will have a webserver (since ``webPort`` is defined)
|
||||
* Are running the ``corda-finance`` CorDapp
|
||||
* Have an RPC user, ``user1``, that can be used to log into the node via RPC
|
||||
6. Download the `NSSM service manager <nssm.cc>`_
|
||||
|
||||
Additionally, all three nodes will include any CorDapps defined in the project's source folders, even though these
|
||||
CorDapps are not listed in each node's ``cordapps`` entry. This means that running the ``deployNodes`` task from the
|
||||
template CorDapp, for example, would automatically build and add the template CorDapp to each node.
|
||||
7. Unzip ``nssm-2.24\win64\nssm.exe`` to ``C:\Corda``
|
||||
|
||||
You can extend ``deployNodes`` to generate additional nodes. The only requirement is that you must specify
|
||||
a single node to run the network map service, by putting their name in the ``networkMap`` field.
|
||||
8. Save the following as ``C:\Corda\nssm.bat``:
|
||||
|
||||
.. warning:: When adding nodes, make sure that there are no port clashes!
|
||||
.. code-block:: batch
|
||||
|
||||
Running deployNodes
|
||||
-------------------
|
||||
To create the nodes defined in our ``deployNodes`` task, we'd run the following command in a terminal window from the
|
||||
root of the project:
|
||||
nssm install cordanode1 C:\ProgramData\Oracle\Java\javapath\java.exe
|
||||
nssm set cordanode1 AppDirectory C:\Corda
|
||||
nssm set cordanode1 AppParameters "-Xmx2048m -jar corda.jar --config-file=C:\corda\node.conf"
|
||||
nssm set cordanode1 AppStdout C:\Corda\service.log
|
||||
nssm set cordanode1 AppStderr C:\Corda\service.log
|
||||
nssm set cordanode1 Description Corda Node - Bank of Breakfast Tea
|
||||
nssm set cordanode1 Start SERVICE_AUTO_START
|
||||
sc start cordanode1
|
||||
|
||||
* Unix/Mac OSX: ``./gradlew deployNodes``
|
||||
* Windows: ``gradlew.bat deployNodes``
|
||||
9. Modify the batch file:
|
||||
|
||||
This will create the nodes in the ``build/nodes`` folder.
|
||||
* If you are installing multiple nodes, use a different service name (``cordanode1``) for each node
|
||||
* Set the amount of Java heap memory available to this node by modifying the -Xmx argument
|
||||
* Set an informative description
|
||||
|
||||
.. warning:: Outside of development environments, do not store your node directories in the build folder.
|
||||
10. Run the batch file by clicking on it or from a command prompt
|
||||
|
||||
There will be a node folder generated for each node you defined, plus a ``runnodes`` shell script (or batch file on
|
||||
Windows) to run all the nodes at once. If you make any changes to your ``deployNodes`` task, you will need to re-run
|
||||
the task to see the changes take effect.
|
||||
11. Run ``services.msc`` and verify that a service called ``cordanode1`` is present and running
|
||||
|
||||
You can now run the nodes by following the instructions in :doc:`Running a node <running-a-node>`.
|
||||
12. Run ``netstat -ano`` and check for the ports you configured in ``node.conf``
|
||||
|
||||
13. You may need to open the ports on the Windows firewall
|
||||
|
||||
Testing your installation
|
||||
-------------------------
|
||||
You can verify Corda is running by connecting to your RPC port from another host, e.g.:
|
||||
|
||||
``telnet your-hostname.example.com 10002``
|
||||
|
||||
If you receive the message "Escape character is ^]", Corda is running and accessible. Press Ctrl-] and Ctrl-D to exit
|
||||
telnet.
|
||||
136
docs/source/generating-a-node.rst
Normal file
136
docs/source/generating-a-node.rst
Normal file
@ -0,0 +1,136 @@
|
||||
Creating nodes locally
|
||||
======================
|
||||
|
||||
.. contents::
|
||||
|
||||
Node structure
|
||||
--------------
|
||||
Each Corda node has the following structure:
|
||||
|
||||
.. sourcecode:: none
|
||||
|
||||
.
|
||||
├── certificates // The node's certificates
|
||||
├── corda-webserver.jar // The built-in node webserver
|
||||
├── corda.jar // The core Corda libraries
|
||||
├── logs // The node logs
|
||||
├── node.conf // The node's configuration files
|
||||
├── persistence.mv.db // The node's database
|
||||
└── plugins // The CorDapps jars installed on the node
|
||||
|
||||
The node is configured by editing its ``node.conf`` file. You install CorDapps on the node by dropping the CorDapp JARs
|
||||
into the ``plugins`` folder.
|
||||
|
||||
Node naming
|
||||
-----------
|
||||
A node's name must be a valid X.500 name that obeys the following additional constraints:
|
||||
|
||||
* The fields of the name have the following maximum character lengths:
|
||||
|
||||
* Common name: 64
|
||||
* Organisation: 128
|
||||
* Organisation unit: 64
|
||||
* Locality: 64
|
||||
* State: 64
|
||||
|
||||
* The country code is a valid ISO 3166-1 two letter code in upper-case
|
||||
|
||||
* The organisation, locality and country attributes are present
|
||||
|
||||
* The organisation field of the name obeys the following constraints:
|
||||
|
||||
* Has at least two letters
|
||||
* No leading or trailing whitespace
|
||||
* No double-spacing
|
||||
* Upper-case first letter
|
||||
* Does not contain the words "node" or "server"
|
||||
* Does not include the characters ',' or '=' or '$' or '"' or '\'' or '\\'
|
||||
* Is in NFKC normalization form
|
||||
* Only the latin, common and inherited unicode scripts are supported
|
||||
|
||||
The Cordform task
|
||||
-----------------
|
||||
Corda provides a gradle plugin called ``Cordform`` that allows you to automatically generate and configure a set of
|
||||
nodes. Here is an example ``Cordform`` task called ``deployNodes`` that creates three nodes, defined in the
|
||||
`Kotlin CorDapp Template <https://github.com/corda/cordapp-template-kotlin/blob/release-V2/build.gradle#L97>`_:
|
||||
|
||||
.. sourcecode:: groovy
|
||||
|
||||
task deployNodes(type: net.corda.plugins.Cordform, dependsOn: ['jar']) {
|
||||
directory "./build/nodes"
|
||||
networkMap "O=Controller,L=London,C=GB"
|
||||
node {
|
||||
name "O=Controller,L=London,C=GB"
|
||||
// The notary will offer a validating notary service.
|
||||
notary = [validating : true]
|
||||
p2pPort 10002
|
||||
rpcPort 10003
|
||||
// No webport property, so no webserver will be created.
|
||||
h2Port 10004
|
||||
// Includes the corda-finance CorDapp on our node.
|
||||
cordapps = ["net.corda:corda-finance:$corda_release_version"]
|
||||
}
|
||||
node {
|
||||
name "O=PartyA,L=London,C=GB"
|
||||
advertisedServices = []
|
||||
p2pPort 10005
|
||||
rpcPort 10006
|
||||
webPort 10007
|
||||
h2Port 10008
|
||||
cordapps = ["net.corda:corda-finance:$corda_release_version"]
|
||||
// Grants user1 all RPC permissions.
|
||||
rpcUsers = [[ user: "user1", "password": "test", "permissions": ["ALL"]]]
|
||||
}
|
||||
node {
|
||||
name "O=PartyB,L=New York,C=US"
|
||||
advertisedServices = []
|
||||
p2pPort 10009
|
||||
rpcPort 10010
|
||||
webPort 10011
|
||||
h2Port 10012
|
||||
cordapps = ["net.corda:corda-finance:$corda_release_version"]
|
||||
// Grants user1 the ability to start the MyFlow flow.
|
||||
rpcUsers = [[ user: "user1", "password": "test", "permissions": ["StartFlow.net.corda.flows.MyFlow"]]]
|
||||
}
|
||||
}
|
||||
|
||||
Running this task will create three nodes in the ``build/nodes`` folder:
|
||||
|
||||
* A ``Controller`` node that:
|
||||
|
||||
* Serves as the network map
|
||||
* Offers a validating notary service
|
||||
* Will not have a webserver (since ``webPort`` is not defined)
|
||||
* Is running the ``corda-finance`` CorDapp
|
||||
|
||||
* ``PartyA`` and ``PartyB`` nodes that:
|
||||
|
||||
* Are pointing at the ``Controller`` as the network map service
|
||||
* Are not offering any services
|
||||
* Will have a webserver (since ``webPort`` is defined)
|
||||
* Are running the ``corda-finance`` CorDapp
|
||||
* Have an RPC user, ``user1``, that can be used to log into the node via RPC
|
||||
|
||||
Additionally, all three nodes will include any CorDapps defined in the project's source folders, even though these
|
||||
CorDapps are not listed in each node's ``cordapps`` entry. This means that running the ``deployNodes`` task from the
|
||||
template CorDapp, for example, would automatically build and add the template CorDapp to each node.
|
||||
|
||||
You can extend ``deployNodes`` to generate additional nodes. The only requirement is that you must specify
|
||||
a single node to run the network map service, by putting its name in the ``networkMap`` field.
|
||||
|
||||
.. warning:: When adding nodes, make sure that there are no port clashes!
|
||||
|
||||
Running deployNodes
|
||||
-------------------
|
||||
To create the nodes defined in our ``deployNodes`` task, run the following command in a terminal window from the root
|
||||
of the project where the ``deployNodes`` task is defined:
|
||||
|
||||
* Linux/macOS: ``./gradlew deployNodes``
|
||||
* Windows: ``gradlew.bat deployNodes``
|
||||
|
||||
This will create the nodes in the ``build/nodes`` folder. There will be a node folder generated for each node defined
|
||||
in the ``deployNodes`` task, plus a ``runnodes`` shell script (or batch file on Windows) to run all the nodes at once
|
||||
for testing and development purposes. If you make any changes to your CorDapp source or ``deployNodes`` task, you will
|
||||
need to re-run the task to see the changes take effect.
|
||||
|
||||
You can now run the nodes by following the instructions in :doc:`Running a node <running-a-node>`.
|
||||
@ -1,25 +1,64 @@
|
||||
Running a node
|
||||
==============
|
||||
Running nodes locally
|
||||
=====================
|
||||
|
||||
Starting your node
|
||||
------------------
|
||||
After following the steps in :doc:`deploying-a-node`, you should have deployed your node(s) with any chosen CorDapps
|
||||
already installed. You run each node by navigating to ``<node_dir>`` in a terminal window and running:
|
||||
.. contents::
|
||||
|
||||
.. note:: You should already have generated your node(s) with their CorDapps installed by following the instructions in
|
||||
:doc:`generating-a-node`.
|
||||
|
||||
There are several ways to run a Corda node locally for testing purposes.
|
||||
|
||||
Starting all nodes at once
|
||||
--------------------------
|
||||
|
||||
.. note:: ``runnodes`` is a shell script (or batch file on Windows) that is generated by ``deployNodes`` to allow you
|
||||
to quickly start up all nodes and their webservers. ``runnodes`` should only be used for testing purposes.
|
||||
|
||||
Start the nodes with ``runnodes`` by running the following command from the root of the project:
|
||||
|
||||
* Linux/macOS: ``build/nodes/runnodes``
|
||||
* Windows: ``call build\nodes\runnodes.bat``
|
||||
|
||||
.. warn:: On macOS, do not click/change focus until all the node terminal windows have opened, or some processes may
|
||||
fail to start.
|
||||
|
||||
If you receive an ``OutOfMemoryError`` exception when interacting with the nodes, you need to increase the amount of
|
||||
Java heap memory available to them, which you can do when running them individually. See
|
||||
:ref:`starting-an-individual-corda-node`.
|
||||
|
||||
.. _starting-an-individual-corda-node:
|
||||
|
||||
Starting an individual Corda node
|
||||
---------------------------------
|
||||
Run the node by opening a terminal window in the node's folder and running:
|
||||
|
||||
.. code-block:: shell
|
||||
|
||||
java -jar corda.jar
|
||||
|
||||
.. warning:: If your working directory is not ``<node_dir>`` your plugins and configuration will not be used.
|
||||
By default, the node will look for a configuration file called ``node.conf`` and a CorDapps folder called ``plugins``
|
||||
in the current working directory. You can override the configuration file and workspace paths on the command line (e.g.
|
||||
``./corda.jar --config-file=test.conf --base-directory=/opt/corda/nodes/test``).
|
||||
|
||||
The configuration file and workspace paths can be overridden on the command line. For example:
|
||||
You can increase the amount of Java heap memory available to the node using the ``-Xmx`` command line argument. For
|
||||
example, the following would run the node with a heap size of 2048MB:
|
||||
|
||||
``./corda.jar --config-file=test.conf --base-directory=/opt/r3corda/nodes/test``.
|
||||
.. code-block:: shell
|
||||
|
||||
Otherwise the workspace folder for the node is the current working path.
|
||||
java -Xmx2048m -jar corda.jar
|
||||
|
||||
Debugging your node
|
||||
-------------------
|
||||
You should do this if you receive an ``OutOfMemoryError`` exception when interacting with the node.
|
||||
|
||||
Optionally run the node's webserver as well by opening a terminal window in the node's folder and running:
|
||||
|
||||
.. code-block:: shell
|
||||
|
||||
java -jar corda-webserver.jar
|
||||
|
||||
.. warning:: The node webserver is for testing purposes only and will be removed soon.
|
||||
|
||||
Starting a node with remote debugging enabled
|
||||
---------------------------------------------
|
||||
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``
|
||||
|
||||
@ -101,7 +101,7 @@ which could be represented as ``{ first: foo, second: 123 }``.
|
||||
|
||||
.. note:: If your CorDapp is written in Java,
|
||||
named arguments won't work unless you compiled using the ``-parameters`` argument to javac.
|
||||
See :doc:`deploying-a-node` for how to specify it via Gradle.
|
||||
See :doc:`generating-a-node` for how to specify it via Gradle.
|
||||
|
||||
The same syntax is also used to specify the parameters for RPCs, accessed via the ``run`` command, like this:
|
||||
|
||||
|
||||
@ -26,7 +26,8 @@ for gradle and IntelliJ, but it's possible this option is not present in your en
|
||||
"No matching constructor found: - [arg0: int, arg1: Party]: missing parameter arg0"
|
||||
***********************************************************************************
|
||||
|
||||
Your CorDapp is written in Java and you haven't specified the ``-parameters`` compiler argument. See :doc:`deploying-a-node` for how it can be done using Gradle.
|
||||
Your CorDapp is written in Java and you haven't specified the ``-parameters`` compiler argument. See
|
||||
:doc:`generating-a-node` for how it can be done using Gradle.
|
||||
|
||||
IDEA issues
|
||||
-----------
|
||||
|
||||
@ -176,7 +176,7 @@ There are two ways to run the example CorDapp:
|
||||
* Via IntelliJ
|
||||
|
||||
In both cases, we will deploy a set of test nodes with our CorDapp installed, then run the nodes. You can read more
|
||||
about how we define the nodes to be deployed :doc:`here <deploying-a-node>`.
|
||||
about how we define the nodes to be deployed :doc:`here <generating-a-node>`.
|
||||
|
||||
Terminal
|
||||
~~~~~~~~
|
||||
|
||||
Loading…
Reference in New Issue
Block a user