ExternalVendorCode/corda
1
0
Fork 0
mirror of https://github.com/corda/corda.git synced 2025-02-05 18:49:14 +00:00
Code Issues Actions 2 Packages Projects Releases Wiki Activity

RELEASE - Release notes and bootstrapper docs for release-3.2

Browse Source 
* 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
This commit is contained in:
Katelyn Baker 2018-07-18 16:52:17 +01:00 committed by GitHub
parent 8585ade599
commit d75da5363a
No known key found for this signature in database
GPG Key ID: 4AEE18F83AFDEB23
3 changed files with 233 additions and 0 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

102
docs/source/network-builder.rst Normal file
View File

@ -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 <network-builder-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 <bootstrapper-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 <network-builder-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 <network-builder-jar> -g``

88
docs/source/release-notes.rst
View File

@ -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://<host>(:<port>)"
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://<host>(:<port>)"
networkMapURL: "http://<host>(:<port>)"
}
.. 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 <https://r3-cev.atlassian.net/browse/CORDA-1744>`_]
* Add the Blob Inspector [`CORDA-1709 <https://r3-cev.atlassian.net/browse/CORDA-1709>`_]
* Add support for the ``Event Horizon`` Network Parameter [`CORDA-866 <https://r3-cev.atlassian.net/browse/CORDA-866>`_]
* Add the Network Bootstrapper [`CORDA-1717 <https://r3-cev.atlassian.net/browse/CORDA-1717>`_]
* Fixes for the finance CordApp[`CORDA-1711 <https://r3-cev.atlassian.net/browse/CORDA-1711>`_]
* Allow Doorman and NetworkMap to be configured independently [`CORDA-1510 <https://r3-cev.atlassian.net/browse/CORDA-1510>`_]
* Serialization fix for generics when evolving a class [`CORDA-1530 <https://r3-cev.atlassian.net/browse/CORDA-1530>`_]
* Correct typo in an internal database table name [`CORDA-1499 <https://r3-cev.atlassian.net/browse/CORDA-1499>`_] and [`CORDA-1804 <https://r3-cev.atlassian.net/browse/CORDA-1804>`_]
* Hibernate session not flushed before handing over raw JDBC session to user code [`CORDA-1548 <https://r3-cev.atlassian.net/browse/CORDA-1548>`_]
* Fix Postgres db bloat issue [`CORDA-1812 <https://r3-cev.atlassian.net/browse/CORDA-1812>`_]
* Roll back flow transaction on exception [`CORDA-1790 <https://r3-cev.atlassian.net/browse/CORDA-1790>`_]
.. _release_notes_v3_1:
Release 3.1

43
docs/source/upgrade-notes.rst
View File

@ -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
------------