From d75da5363a29e8bb961cf0d2b05724662ddddce7 Mon Sep 17 00:00:00 2001 From: Katelyn Baker Date: Wed, 18 Jul 2018 16:52:17 +0100 Subject: [PATCH] RELEASE - Release notes and bootstrapper docs for release-3.2 * RELEASE: initial changes to release docs * wip * wip * Upgrade notes for a table name change. (#3566) Document table change name from v3.0 to v3.2, change introduced in v3.1 but not mentioned in v3.1 upgrade notes, back-port of PR #3567. * wip * wip * wip * CORDA-1812 - upgrade notes (#3618) * CORDA-1812 upgrade notes * CORDA-1812 upgrade notes * CORDA-1804 - upgrade notes for CORDA-1804 (#3619) * Missing upgrade notes for table change in v3.1 - related to CORDA-1804 (#3567) Document different upgrade notes for table name change from v3.0 or from v3.1/v3.2 to the current version (a table change introduced in v3.1 was not documented in upgrade notes). (cherry picked from commit 9f905da036622526e0b198b1c3e67fbbf98c6ca5) * Move different table name upgrade paths under one section. * Addressing PR comments. * Addressing PR comments. * review comments * WIP * WIP * WIP * Doc for bootstrapper (#3638) * network-builder-docs * docs for network-builder * wip@ * final comments --- docs/source/network-builder.rst | 102 ++++++++++++++++++++++++++++++++ docs/source/release-notes.rst | 88 +++++++++++++++++++++++++++ docs/source/upgrade-notes.rst | 43 ++++++++++++++ 3 files changed, 233 insertions(+) create mode 100644 docs/source/network-builder.rst diff --git a/docs/source/network-builder.rst b/docs/source/network-builder.rst new file mode 100644 index 0000000000..4d12e8e3ce --- /dev/null +++ b/docs/source/network-builder.rst @@ -0,0 +1,102 @@ +Corda Network Builder +===================== + +The corda network builder is a way to build dynamic networks for testing. It leverages docker and containers to abstract +as much of the complexity of managing a distributed network away from the user. + +At the moment, there are integrations for `docker` and `azure container service` + +Prerequisites +------------- + +:docker: + docker > 17.12.0-ce + +:azure: + authenticated az-cli >= 2.0 (see: https://docs.microsoft.com/en-us/cli/azure/install-azure-cli?view=azure-cli-latest) + +Building a network +------------------ + +The network builder uses node docker images as the base for all other operations. A "node" is anything that satisfies +the following layout + +:: + + - + -- node.conf + -- corda.jar + -- cordapps/ + + +An easy way to build a compliant set of nodes is to use the ``deployNodes`` utility. In this document, we will be using the output of ``deployNodes`` of the ``bank-of-corda-demo`` sample available in the main corda repository. + +Quickstart Local Docker +~~~~~~~~~~~~~~~~~~~~~~~ + +1. ``./gradlew clean samples:bank-of-corda-demo:deployNodes`` +2. ``cd samples/bank-of-corda-demo/build/nodes`` +3. ``java -jar -d .`` +4. ``docker ps`` + +The following output should be displayed + +:: + + CONTAINER ID IMAGE COMMAND CREATED STATUS PORTS NAMES + 8b65c104ba7c node-bigcorporation:corda-network "/run-corda.sh" 14 seconds ago Up 13 seconds 0.0.0.0:32788->10003/tcp, 0.0.0.0:32791->10005/tcp, 0.0.0.0:32790->10020/tcp, 0.0.0.0:32789->12222/tcp bigcorporation0 + 3a7af5543c3a node-bankofcorda:corda-network "/run-corda.sh" 14 seconds ago Up 13 seconds 0.0.0.0:32787->10003/tcp, 0.0.0.0:32786->10005/tcp, 0.0.0.0:32785->10020/tcp, 0.0.0.0:32784->12222/tcp bankofcorda0 + a7b84444feed node-notaryservice:corda-network "/run-corda.sh" 23 seconds ago Up 22 seconds 0.0.0.0:32783->10003/tcp, 0.0.0.0:32782->10005/tcp, 0.0.0.0:32781->10020/tcp, 0.0.0.0:32780->12222/tcp notaryservice0 + +to interact with the nodes, it is possible to ssh into the nodes via the port 12222 mapping, for example to ssh into the `bankofcorda0` node + +:: + + ssh bankUser@localhost -p 32784 + Password authentication + Password: + + + Welcome to the Corda interactive shell. + Useful commands include 'help' to see what is available, and 'bye' to shut down the node. + + >>> run networkMapSnapshot + [ + {"legalIdentities":[{"name":"O=BankOfCorda, L=London, C=GB"}],"addresses":["bankofcorda0:10020"],"serial":1531841642785,"platformVersion":3}, + {"legalIdentities":[{"name":"O=Notary Service, L=Zurich, C=CH"}],"addresses":["notaryservice0:10020"],"serial":1531841631144,"platformVersion":3}, + {"legalIdentities":[{"name":"O=BigCorporation, L=New York, C=US"}],"addresses":["bigcorporation0:10020"],"serial":1531841642864,"platformVersion":3} + ] + + >>> + +now that the node images have been built, it is possible to add nodes reusing the same images. To add a node reusing the `BankOfCorda` base image. + +``java -jar --add "BankOfCorda=O=WayTooBigToFailBank,L=London,C=GB"`` + +And to confirm the node has been started correctly in the previously connected ssh session + +:: + + Tue Jul 17 15:47:14 GMT 2018>>> run networkMapSnapshot + [ + {"legalIdentities":[{"name":"O=BankOfCorda, L=London, C=GB"}],"addresses":["bankofcorda0:10020"],"serial":1531841642785,"platformVersion":3}, + {"legalIdentities":[{"name":"O=Notary Service, L=Zurich, C=CH"}],"addresses":["notaryservice0:10020"],"serial":1531841631144,"platformVersion":3}, + {"legalIdentities":[{"name":"O=BigCorporation, L=New York, C=US"}],"addresses":["bigcorporation0:10020"],"serial":1531841642864,"platformVersion":3}, + {"legalIdentities":[{"name":"O=WayTooBigToFailBank, L=London, C=GB"}],"addresses":["bankofcorda1:10020"],"serial":1531842358730,"platformVersion":3} + ] + +Quickstart Remote Azure +~~~~~~~~~~~~~~~~~~~~~~~ + +1. ``./gradlew clean samples:bank-of-corda-demo:deployNodes`` +2. ``cd samples/bank-of-corda-demo/build/nodes`` +3. ``java -jar -b AZURE -d .`` + +.. note:: Azure configuration is handled per the az-cli utility, see pre-reqs at the start of the document + +Graphical User Mode +~~~~~~~~~~~~~~~~~~~ + +The corda network builder also provides a GUI for when automated interactions are not required to launch this run +``java -jar -g`` + diff --git a/docs/source/release-notes.rst b/docs/source/release-notes.rst index fba39537be..45bbaa28e2 100644 --- a/docs/source/release-notes.rst +++ b/docs/source/release-notes.rst @@ -1,6 +1,94 @@ Release notes ============= +.. _release_notes_v3_2: + +Release 3.2 +----------- + +As we see more Corda deployments in production this minor release of the open source platform brings +several fixes that make it easier for a node to join Corda networks broader than those used when +operating as part of an internal testing deployment. This will ensure Corda nodes will be free to interact +with upcoming network offerings from R3 and others who may make broad-access Corda networks available. + +* **The Corda Network Builder** + +To make it easier to create more dynamic, flexible, networks for testing and deployment, +with the 3.2 release of Corda we are shipping a graphical network bootsrapping tool (see :doc:`network-builder`) +to facilitate the simple creation of more dynamic ad hoc dev-mode environments. + +Using a graphical interface you can dynamically create and alter Corda test networks, adding +nodes and CorDapps with the click of a button! Additionally, you can leverage its integration +with Azure cloud services for remote hosting of Nodes and Docker instances for local testing. + +* **Split Compatibility Zone** + +Prior to this release compatibility zone membership was denoted with a single configuration setting + +.. sourcecode:: shell + + compatibilityZoneURL : "http://(:)" + +That would indicate both the location of the Doorman service the node should use for registration +of its identity as well as the Network Map service where it would publish its signed Node Info and +retrieve the Network Map. + +Compatibility Zones can now, however, be configured with the two disparate services, Doorman and +Network Map, running on different URLs. If the compatibility zone your node is connecting to +is configured in this manner, the new configuration looks as follows. + +.. sourcecode:: shell + + networkServices { + doormanURL: "http://(:)" + networkMapURL: "http://(:)" + } + +.. note:: The ``compatibilityZoneURL`` setting should be considered deprecated in favour of the new + ``networkServices`` settings group. + +* **The Blob Inspector** + +The blob inspector brings the ability to unpack serialized Corda blobs at the +command line, giving a human readable interpretation of the encoded date. + +.. note:: This tool has been shipped as a separate Jar previously. We are now including it + as part of an official release. + +Documentation on its use can be found here :doc:`blob-inspector` + +* **The Event Horizon** + +One part of joining a node to a Corda network is agreeing to the rules that govern that network as set out +by the network operator. A node's membership of a network is communicated to other nodes through the network +map, the service to which the node will have published its Node Info, and through which it receives the +set of NodeInfos currently present on the network. Membership of that list is a finite thing determined by +the network operator. + +Periodically a node will republish its NodeInfo to the Nework Map service. The Network Map uses this as a +heartbeat to determine the status of nodes registered with it. Those that don't "beep" within the +determined interval are removed from the list of registered nodes. The ``Event Horizon`` network parameter +sets the upper limit within which a node must respond or be considered inactive. + +.. important:: This does not mean a node is unregistered from the Doorman, only that its NodeInfo is + removed from the Network Map. Should the node come back online it will be re-added to the published + set of NodeInfos + +Issues Fixed +~~~~~~~~~~~~ + +* Update Jolokia to a more secure version [`CORDA-1744 `_] +* Add the Blob Inspector [`CORDA-1709 `_] +* Add support for the ``Event Horizon`` Network Parameter [`CORDA-866 `_] +* Add the Network Bootstrapper [`CORDA-1717 `_] +* Fixes for the finance CordApp[`CORDA-1711 `_] +* Allow Doorman and NetworkMap to be configured independently [`CORDA-1510 `_] +* Serialization fix for generics when evolving a class [`CORDA-1530 `_] +* Correct typo in an internal database table name [`CORDA-1499 `_] and [`CORDA-1804 `_] +* Hibernate session not flushed before handing over raw JDBC session to user code [`CORDA-1548 `_] +* Fix Postgres db bloat issue [`CORDA-1812 `_] +* Roll back flow transaction on exception [`CORDA-1790 `_] + .. _release_notes_v3_1: Release 3.1 diff --git a/docs/source/upgrade-notes.rst b/docs/source/upgrade-notes.rst index 59f3ca5426..2f2a857fbd 100644 --- a/docs/source/upgrade-notes.rst +++ b/docs/source/upgrade-notes.rst @@ -28,6 +28,49 @@ versions you are currently using are still in force. We also strongly recommend cross referencing with the :doc:`changelog` to confirm changes. +v3.1 to v3.2 +------------ + +Gradle Plugin Version +^^^^^^^^^^^^^^^^^^^^^ + +You will need to update the ``corda_release_version`` identifier in your project gradle file. + +.. sourcecode:: shell + + ext.corda_release_version = '3.2-corda' + +Database schema changes +^^^^^^^^^^^^^^^^^^^^^^^ + +* Database upgrade - a typo has been corrected in the ``NODE_ATTACHMENTS_CONTRACTS`` table name. +When upgrading from version 3.1, run the following command: + +.. sourcecode:: sql + + ALTER TABLE [schema].NODE_ATTCHMENTS_CONTRACTS RENAME TO NODE_ATTACHMENTS_CONTRACTS; + +When upgrading from version 3.0, run the following command: + +.. sourcecode:: sql + + ALTER TABLE [schema].NODE_ATTACHMENTS_CONTRACT_CLASS_NAME RENAME TO NODE_ATTACHMENTS_CONTRACTS; + +Schema name is optional, run SQL when the node is not running. + +* Postgres database upgrade - Change the type of the ``checkpoint_value`` column to ``bytea``. +This will address the issue that the `vacuum` function is unable to clean up deleted checkpoints as they are still referenced from the ``pg_shdepend`` table. + + .. sourcecode:: sql + + ALTER TABLE node_checkpoints ALTER COLUMN checkpoint_value set data type bytea using null; + + .. note:: + This change will also need to be run when migrating from version 3.0. + +.. note:: + The Corda node will fail on startup if the database was not updated with the above commands. + v3.0 to v3.1 ------------