Upgrading to Contour 8.1

This guide is for upgrading from Contour v8.0 to Contour v8.1, with assumption that Contour v8.0 is running on the recommended Corda Enterprise version (CE4.8).

Contour releases strive to be backwards compatible, and use Liquibase for the Database schema versioning. With Corda Enterprise and Springboot supporting Liquibase, upgrading a Contour node is fairly straightforward.

Corda Open Source (OS) doesn't support Liquibase. Therefore, if a node is running on Corda OS, the nodes needs to be upgraded to CE first, before upgrading Contour version.

Upgrading Contour consistis of the following steps:

Stop the node
[IMPORTANT] Back up the node directories AND database
Upgrade Contour Cordapps
Upgrade Contour Web Apps

Step 1. Stop the node

Stop the node in the sequence that:

Stop the Contour Web Application, e.g. systemctl stop contour.service if using systemd
Drain the Corda node
- Connect to the Corda Shell using the command ssh -p [sshd portNumber] [rpc username]@[host, e.g. localhost]
  - e.g. ssh -p 2222 cordau@localhost
- Key in rpc userpassword as specified in the Corda node.conf
- Run the command run setFlowsDrainingModeEnabled enabled: true to do a flow drain
- Run the command run stateMachinesSnapshot to check that there is no in-flight flows
  - If the result is empty list [], it means all flows have completed, proceed to stop the Corda node
  - If the result is not an empty list, which means there are some in-flight flows as listed in the result, wait until these flows complete, and/or investigate why they are stuck and whether safe to kill.
Once all flows have completed, stop the Corda node, e.g. systemctl stop corda.service if using systemd

Step 2. Backup the node

[IMPORTANT] Any upgrade, especially database schema migration, come with risk. Thus, it's very important that the node is back up before upgrading. With backup, a node can be restored fairly easily.

Backup the Contour Web App folder directory, e.g. cp -R api-service/ api-service-8-0-backup/;
Backup the Corda folder directory, e.g. cp -R corda/ corda-8-0-backup/;
Backup the Contour Web App database and Corda database, Backup recommendations.

Reference to restore a corda node: Backup and restoration of a Corda node

Step 3. Upgrade Contour Cordapps

Contour v8.1 runs on Corda Enterprise (CE) 4.8.6, same as Contour v8.0.

3.1. Replace Cordapps Jars

Under the corda > cordapps directory, e.g. /opt/corda/cordapps:

Delete the old version jars
- All the Flow jars: rm contour-cordapp-8.0.0.jar
- All the Contracts and States jar: rm contour-cordapp-contracts-and-states-8.0.0.jar
Copy & paste in all the new version jars from Contour release package, contour-8-1/corda/cordapps/.
- All the Flow jars:
  - contour-cordapp-8.1.1.jar
  - contour-business-tools-cordapp-8.1.1.jar
- All the Contracts and States jar: contour-cordapp-contracts-and-states-cordapp-8.1.1.jar

3.2. Update Cordapp config

The following flow jar requires configurations:

contour-cordapp-8.1.1.jar

Corda will automaticially match each flow jar to its configuration under the corda > cordapps > config directory (e.g. /opt/corda/cordapps/config), based on the flow jar name. Therefore, the configuration files must be named correctly, matching to the flow jar name. i.e.

contour-cordapp-8.1.1.conf for contour-cordapp-8.1.1.jar

Therefore, the steps to update the configuration will be:

Rename the config file name for flow jar contour-cordapp-8.1.1.jar to match the new version, i.e. from contour-cordapp-8.0.0.conf to contour-cordapp-8.1.1.conf.
- No change in the contour-cordapp-8.1.1.conf in v8.1 required, compared to v8.0.
- Refer to Contour Corda Config for more details about the configuration parameters

3.3. Update the database

Start the node with the run-migration-scripts sub-command with --core-schemas and --app-schemas.

Command: java -jar corda-4.8.6.jar run-migration-scripts --core-schemas --app-schemas

The node will perform any automatic data migrations required, which may take some time. If the migration process is interrupted it can be continued simply by starting the node again, without harm. The node will stop automatically when migration is complete.

3.4. Start Corda in the normal way

Start the Corda in the normal way, e.g.

java -jar corda-4.8.6.jar --base-directory /opt/corda --config-file /opt/corda/node.conf; or
systemctl start corda.service if using systemd

3.5. Undrain the node

You may now do any checks that you wish to perform, read the logs, and so on. When you are ready, use this command at the Corda shell: run setFlowsDrainingModeEnabled enabled: false

Step 4. Upgrade Contour WebApp

4.1. Replace Web App

Under the contour webapp directory, e.g. /opt/api-services:

Delete the old version jar and static asset
- Sprint Boot jar: rm contour-service-8.0.0.jar; and
- Static asset folder: rm -rf static/
Copy & paste in the new version of Contour web app jar and static asset folder from Contour release package, contour-8.1/api-service/
- Sprint Boot jar: contour-service-8.1.1.jar and
- Static asset folder: static/

4.2. Update WebApp configuration

Update the Contour Web APP (Spring Boot) configuration (if necessary)

Update application.properties file when upgrading from 8.0 to 8.1
- Append the below parameters for JDBC connection if you are using MSSQL DB server
  - encrypt=true;trustServerCertificate=true, for example: update from jdbc:sqlserver://DB_HOST:1433;databaseName=DB_Name to jdbc:sqlserver://DB_HOST:1433;databaseName=DB_Name;encrypt=true;trustServerCertificate=true
- Update the Contour version:
  - info.app.version="contour-service-8.1.1.jar"
  - info.cordapp.version="8.1.1"
  - info.cordapp.contract.version="8.1.1-release"
Refer to Contour WebApp Config for more details about the configuration parameters

4.3. Start Contour Web App

Start the Contour web app as normal, e.g.

java -jar contour-service-8.1.1.jar -Dspring.profiles.active=local,CentralPortal,hascorda,prod,auth; or
systemctl start contour.service if using systemd

Spring Boot will handle the Liquibase database schema migration.