mirror of
https://github.com/corda/corda.git
synced 2024-12-24 23:26:48 +00:00
Backports changes to docs on generating and running nodes.
This commit is contained in:
Joel Dudley
GitHub
parent
139c15faec
commit
a94ca991cd
@ -126,10 +126,10 @@ path to the node's base directory.
|
|||||||
|
|
||||||
:username: Username consisting only of word characters (a-z, A-Z, 0-9 and _)
|
:username: Username consisting only of word characters (a-z, A-Z, 0-9 and _)
|
||||||
:password: The password
|
:password: The password
|
||||||
:permissions: A list of permission strings which RPC methods can use to control access
|
: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
|
||||||
If this field is absent or an empty list then RPC is effectively locked down. Alternatively, if it contains the string
|
contains the string ``ALL``, the user can start any flow via RPC. This value is intended for administrator
|
||||||
``ALL`` then the user is permitted to use *any* RPC method. This value is intended for administrator users and for developers.
|
users and for development.
|
||||||
|
|
||||||
:devMode: This flag sets the node to run in development mode. On startup, if the keystore ``<workspace>/certificates/sslkeystore.jks``
|
: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
|
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.
|
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
|
: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::
|
.. toctree::
|
||||||
:maxdepth: 1
|
:maxdepth: 1
|
||||||
|
|
||||||
deploying-a-node
|
generating-a-node
|
||||||
running-a-node
|
running-a-node
|
||||||
|
deploying-a-node
|
||||||
corda-configuration-file
|
corda-configuration-file
|
||||||
clientrpc
|
clientrpc
|
||||||
shell
|
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
|
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.
|
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
|
.. warning:: The hash of the generated CorDapp JAR is not deterministic, as it depends on variables such as the
|
||||||
at creation. Nodes running the same CorDapp must therefore ensure they are using the exact same CorDapp jar, and not
|
timestamp at creation. Nodes running the same CorDapp must therefore ensure they are using the exact same CorDapp
|
||||||
different versions of the JAR created from identical sources.
|
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.
|
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
|
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
|
.. 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
|
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
|
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
|
Deploying a node
|
||||||
================
|
================
|
||||||
|
|
||||||
Node structure
|
.. contents::
|
||||||
--------------
|
|
||||||
Each Corda node has the following structure:
|
|
||||||
|
|
||||||
.. 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.
|
||||||
|
|
||||||
.
|
Linux: Installing and running Corda as a system service
|
||||||
├── certificates // The node's doorman certificates
|
-------------------------------------------------------
|
||||||
├── corda-webserver.jar // The built-in node webserver
|
We recommend creating system services to run a node and the optional webserver. This provides logging and service
|
||||||
├── corda.jar // The core Corda libraries
|
handling, and ensures the Corda service is run at boot.
|
||||||
├── 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
|
**Prerequisites**:
|
||||||
into the ``plugins`` folder.
|
|
||||||
|
|
||||||
Node naming
|
* Oracle Java 8. The supported versions are listed in :doc:`getting-set-up`
|
||||||
-----------
|
|
||||||
A node's name must be a valid X500 name that obeys the following additional constraints:
|
|
||||||
|
|
||||||
* 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
|
``sudo adduser --system --no-create-home --group corda``
|
||||||
* Organisation: 128
|
|
||||||
* Organisation unit: 64
|
|
||||||
* Locality: 64
|
|
||||||
* State: 64
|
|
||||||
|
|
||||||
* 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
|
4. (Optional) Download the `Corda webserver jar <http://r3.bintray.com/corda/net/corda/corda-webserver/>`_
|
||||||
* No leading or trailing whitespace
|
(under ``/VERSION_NUMBER/corda-VERSION_NUMBER.jar``) and place it in ``/opt/corda``
|
||||||
* 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 deployNodes task
|
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
|
||||||
The CorDapp template defines a ``deployNodes`` task that allows you to automatically generate and configure a set of
|
|
||||||
nodes:
|
|
||||||
|
|
||||||
.. 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']) {
|
.. code-block:: json
|
||||||
directory "./build/nodes"
|
|
||||||
networkMap "O=Controller,L=London,C=GB"
|
basedir : "/opt/corda"
|
||||||
node {
|
p2pAddress : "example.com:10002"
|
||||||
name "O=Controller,L=London,C=GB"
|
rpcAddress : "example.com:10003"
|
||||||
// The notary will offer a validating notary service.
|
webAddress : "0.0.0.0:10004"
|
||||||
// Set to `corda.notary.simple` for a non-validating notary.
|
h2port : 11000
|
||||||
advertisedServices = ["corda.notary.validating"]
|
emailAddress : "you@example.com"
|
||||||
p2pPort 10002
|
myLegalName : "O=Bank of Breakfast Tea, L=London, C=GB"
|
||||||
rpcPort 10003
|
keyStorePassword : "cordacadevpass"
|
||||||
// No webport property, so no webserver will be created.
|
trustStorePassword : "trustpass"
|
||||||
h2Port 10004
|
useHTTPS : false
|
||||||
sshdPort 22
|
devMode : false
|
||||||
// Includes the corda-finance CorDapp on our node.
|
networkMapService {
|
||||||
cordapps = ["net.corda:corda-finance:$corda_release_version"]
|
address="networkmap.foo.bar.com:10002"
|
||||||
|
legalName="O=FooBar NetworkMap, L=Dublin, C=IE"
|
||||||
}
|
}
|
||||||
node {
|
rpcUsers=[
|
||||||
name "O=PartyA,L=London,C=GB"
|
{
|
||||||
advertisedServices = []
|
user=corda
|
||||||
p2pPort 10005
|
password=portal_password
|
||||||
rpcPort 10006
|
permissions=[
|
||||||
webPort 10007
|
ALL
|
||||||
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 = []
|
7. Make the following changes to ``/opt/corda/node.conf``:
|
||||||
p2pPort 10009
|
|
||||||
rpcPort 10010
|
* Change the ``p2pAddress`` and ``rpcAddress`` values to start with your server's hostname or external IP address.
|
||||||
webPort 10011
|
This is the address other nodes or RPC interfaces will use to communicate with your node
|
||||||
h2Port 10012
|
* Change the ports if necessary, for example if you are running multiple nodes on one server (see below)
|
||||||
sshdPort 22
|
* Enter an email address which will be used as an administrative contact during the registration process. This is
|
||||||
cordapps = ["net.corda:corda-finance:$corda_release_version"]
|
only visible to the permissioning service
|
||||||
// Grants user1 the ability to start the MyFlow flow.
|
* Enter your node's desired legal name. This will be used during the issuance of your certificate and should rarely
|
||||||
rpcUsers = [[ user: "user1", "password": "test", "permissions": ["StartFlow.net.corda.flows.MyFlow"]]]
|
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"
|
||||||
}
|
}
|
||||||
|
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
|
* Organization (``O=``) should be a unique and meaningful identifier (e.g. Bank of Breakfast Tea)
|
||||||
* Offers a validating notary service
|
* Location (``L=``) is your nearest city
|
||||||
* Will not have a webserver (since ``webPort`` is not defined)
|
* Country (``C=``) is the `ISO 3166-1 alpha-2 code <https://en.wikipedia.org/wiki/ISO_3166-1_alpha-2>`_
|
||||||
* Is running the ``corda-finance`` CorDapp
|
* 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
|
6. Download the `NSSM service manager <nssm.cc>`_
|
||||||
* 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
|
7. Unzip ``nssm-2.24\win64\nssm.exe`` to ``C:\Corda``
|
||||||
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
|
8. Save the following as ``C:\Corda\nssm.bat``:
|
||||||
a single node to run the network map service, by putting their name in the ``networkMap`` field.
|
|
||||||
|
|
||||||
.. warning:: When adding nodes, make sure that there are no port clashes!
|
.. code-block:: batch
|
||||||
|
|
||||||
Running deployNodes
|
nssm install cordanode1 C:\ProgramData\Oracle\Java\javapath\java.exe
|
||||||
-------------------
|
nssm set cordanode1 AppDirectory C:\Corda
|
||||||
To create the nodes defined in our ``deployNodes`` task, we'd run the following command in a terminal window from the
|
nssm set cordanode1 AppParameters "-Xmx2048m -jar corda.jar --config-file=C:\corda\node.conf"
|
||||||
root of the project:
|
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``
|
9. Modify the batch file:
|
||||||
* Windows: ``gradlew.bat deployNodes``
|
|
||||||
|
|
||||||
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
|
11. Run ``services.msc`` and verify that a service called ``cordanode1`` is present and running
|
||||||
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.
|
|
||||||
|
|
||||||
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
|
.. contents::
|
||||||
------------------
|
|
||||||
After following the steps in :doc:`deploying-a-node`, you should have deployed your node(s) with any chosen CorDapps
|
.. note:: You should already have generated your node(s) with their CorDapps installed by following the instructions in
|
||||||
already installed. You run each node by navigating to ``<node_dir>`` in a terminal window and running:
|
: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
|
.. code-block:: shell
|
||||||
|
|
||||||
java -jar corda.jar
|
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:
|
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``
|
``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,
|
.. note:: If your CorDapp is written in Java,
|
||||||
named arguments won't work unless you compiled using the ``-parameters`` argument to javac.
|
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:
|
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"
|
"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
|
IDEA issues
|
||||||
-----------
|
-----------
|
||||||
|
|||||||
@ -176,7 +176,7 @@ There are two ways to run the example CorDapp:
|
|||||||
* Via IntelliJ
|
* 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
|
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
|
Terminal
|
||||||
~~~~~~~~
|
~~~~~~~~
|
||||||
|
|||||||
Loading…
Reference in New Issue
Block a user