diff --git a/docs/source/corda-configuration-file.rst b/docs/source/corda-configuration-file.rst index 42af820033..346d92ff90 100644 --- a/docs/source/corda-configuration-file.rst +++ b/docs/source/corda-configuration-file.rst @@ -102,24 +102,26 @@ path to the node's base directory. :notary: Optional configuration object which if present configures the node to run as a notary. If part of a Raft or BFT SMaRt cluster then specify ``raft`` or ``bftSMaRt`` respectively as described below. If a single node notary then omit both. - :validating: Boolean to determine whether the notary is a validating or non-validating one. + :validating: Boolean to determine whether the notary is a validating or non-validating one. - :raft: If part of a distributed Raft cluster specify this config object, with the following settings: + :raft: If part of a distributed Raft cluster specify this config object, with the following settings: - :nodeAddress: The host and port to which to bind the embedded Raft server. Note that the Raft cluster uses a - separate transport layer for communication that does not integrate with ArtemisMQ messaging services. + :nodeAddress: The host and port to which to bind the embedded Raft server. Note that the Raft cluster uses a + separate transport layer for communication that does not integrate with ArtemisMQ messaging services. - :clusterAddresses: List of Raft cluster member addresses used to join the cluster. At least one of the specified - members must be active and be able to communicate with the cluster leader for joining. If empty, a new - cluster will be bootstrapped. + :clusterAddresses: Must list the addresses of all the members in the cluster. At least one of the members must + be active and be able to communicate with the cluster leader for the node to join the cluster. If empty, a + new cluster will be bootstrapped. - :bftSMaRt: If part of a distributed BFT-SMaRt cluster specify this config object, with the following settings: + :bftSMaRt: If part of a distributed BFT-SMaRt cluster specify this config object, with the following settings: - :replicaId: The zero-based index of the current replica. All replicas must specify a unique replica id. + :replicaId: The zero-based index of the current replica. All replicas must specify a unique replica id. - :clusterAddresses: List of all BFT-SMaRt cluster member addresses. + :clusterAddresses: Must list the addresses of all the members in the cluster. At least one of the members must + be active and be able to communicate with the cluster leader for the node to join the cluster. If empty, a + new cluster will be bootstrapped. - :custom: If `true`, will load and install a notary service from a CorDapp. See :doc:`tutorial-custom-notary`. + :custom: If `true`, will load and install a notary service from a CorDapp. See :doc:`tutorial-custom-notary`. Only one of ``raft``, ``bftSMaRt`` or ``custom`` configuration values may be specified. @@ -130,12 +132,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 ``/certificates/sslkeystore.jks`` does not exist, a developer keystore will be used if ``devMode`` is true. The node will exit if ``devMode`` is false @@ -164,4 +166,4 @@ path to the node's base directory. :sshd: If provided, node will start internal SSH server which will provide a management shell. It uses the same credentials and permissions as RPC subsystem. It has one required parameter. - :port: - the port to start SSH server on + :port: The port to start SSH server on diff --git a/docs/source/corda-nodes-index.rst b/docs/source/corda-nodes-index.rst index 16a95a19a1..c1dfa0b508 100644 --- a/docs/source/corda-nodes-index.rst +++ b/docs/source/corda-nodes-index.rst @@ -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 diff --git a/docs/source/cordapp-build-systems.rst b/docs/source/cordapp-build-systems.rst index a203f75160..bfbe08662c 100644 --- a/docs/source/cordapp-build-systems.rst +++ b/docs/source/cordapp-build-systems.rst @@ -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 CorDapps present in their ``cordapps`` folder. Therefore in order to install a CorDapp on a node, the CorDapp JAR must be added to the ``/cordapps/`` folder, where ``node_dir`` is the folder in which diff --git a/docs/source/deploying-a-node.rst b/docs/source/deploying-a-node.rst index 6bda43ca86..2b091fddf8 100644 --- a/docs/source/deploying-a-node.rst +++ b/docs/source/deploying-a-node.rst @@ -1,141 +1,242 @@ 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 - └── cordapps // The CorDapps jars installed on the node +Linux (systemd): Installing and running Corda as a systemd service +------------------------------------------------------------------ +We recommend creating systemd 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 ``cordapps`` 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 `_ + (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 +3. Create a directory called ``plugins`` in ``/opt/corda`` and save your CorDapp jar file to it. Alternatively, download one of + our `sample CorDapps `_ to the ``plugins`` directory -The deployNodes task --------------------- -The CorDapp template defines a ``deployNodes`` task that allows you to automatically generate and configure a set of -nodes: +4. Save the below as ``/opt/corda/node.conf``. See :doc:`corda-configuration-file` for a description of these options -.. sourcecode:: groovy + .. code-block:: json - 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 - sshdPort 22 - // Includes the corda-finance CorDapp on our node. - cordapps = ["net.corda:corda-finance:$corda_release_version"] + 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 + ] + } + ] + +5. 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 `_ + * Change the RPC username and password + +6. 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 + +7. Make the following changes to ``corda.service``: + + * 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 is not root** + * Set the maximum amount of memory available to the Corda process by changing the ``-Xmx2048m`` parameter + * 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`` + +.. note:: The Corda webserver provides a simple interface for interacting with your installed CorDapps in a browser. + Running the webserver is optional. + +8. 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=username + WorkingDirectory=/opt/corda + ExecStart=/usr/bin/java -jar /opt/corda/corda-webserver.jar + Restart=on-failure + + [Install] + WantedBy=multi-user.target + +9. Provision the required certificates to your node. Contact the network permissioning service or see + :doc:`permissioning` + +10. You can now start a node and its webserver by running the following ``systemctl`` commands: + + * ``sudo systemctl daemon-reload`` + * ``sudo systemctl corda start`` + * ``sudo systemctl corda-webserver start`` + +You can run multiple nodes by creating multiple directories and Corda services, modifying the ``node.conf`` and +``service`` 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 `_ 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 `_ + * 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 `_ -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 "-jar corda.jar -Xmx2048m --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 + 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 -.. note:: During the build process each node generates a NodeInfo file which is written in its own root directory, - the plug-in proceeds and copies each node NodeInfo to every other node ``additional-node-infos`` directory. - The NodeInfo file contains a node hostname and port, legal name and security certificate. +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 `. \ No newline at end of file +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. \ No newline at end of file diff --git a/docs/source/generating-a-node.rst b/docs/source/generating-a-node.rst new file mode 100644 index 0000000000..afbde7127c --- /dev/null +++ b/docs/source/generating-a-node.rst @@ -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 + └── cordapps // 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 ``cordapps`` 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 `_: + +.. 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 `. \ No newline at end of file diff --git a/docs/source/running-a-node.rst b/docs/source/running-a-node.rst index 4373e93a3e..b5c2ddf845 100644 --- a/docs/source/running-a-node.rst +++ b/docs/source/running-a-node.rst @@ -1,25 +1,49 @@ -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 ```` 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. + +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 ```` your cordapps and configuration will not be used. +.. warning:: By default, the node will look for a configuration file called ``node.conf`` and a CorDapps folder called + ``cordapps`` 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/r3corda/nodes/test``). -The configuration file and workspace paths can be overridden on the command line. For example: +Optionally run the node's webserver as well by opening a terminal window in the node's folder and running: -``./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 -jar corda-webserver.jar -Debugging your node -------------------- +.. 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`` diff --git a/docs/source/shell.rst b/docs/source/shell.rst index 2fc11829b2..d993c5e3bf 100644 --- a/docs/source/shell.rst +++ b/docs/source/shell.rst @@ -137,7 +137,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: diff --git a/docs/source/troubleshooting.rst b/docs/source/troubleshooting.rst index 51e60133c4..4176f04ed3 100644 --- a/docs/source/troubleshooting.rst +++ b/docs/source/troubleshooting.rst @@ -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 ----------- diff --git a/docs/source/tutorial-cordapp.rst b/docs/source/tutorial-cordapp.rst index d8dfcff998..7873819f82 100644 --- a/docs/source/tutorial-cordapp.rst +++ b/docs/source/tutorial-cordapp.rst @@ -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 `. +about how we define the nodes to be deployed :doc:`here `. Terminal ~~~~~~~~