Upgrading a Cluster with Context Graph

Before upgrading, be sure to read the release notes for the new version. The release notes contain a list of known issues, important compatibility information, supported upgrade paths, and module-specific data backup recommendations.
Apply all the latest updates available for your operating system, especially those that resolve issues with Java.
Install all patches and updates in an earlier version of Spectrum Technology Platform before you upgrade to Spectrum Technology Platform 2020.1.0
Important: We recommend that you create a backup before upgrading so that if an error occurs during the upgrade you can recover your flows, security settings, and other settings and customizations, if an error occurs during the upgrade process.
To retain customized settings in the wrapper.conf file located in the SpectrumDirectory/server/bin/wrapper directory, you will need to compare the contents of wrapper.conf installed during the upgrade with the contents of the backed up copy of the file. You can then manually copy customizations that you want to retain after the upgrade into the updated version of the file. This is particularly important for changes to the initial and maximum Java heap sizes.

In a cluster that runs Context Graph, each node hosts the Spectrum Technology Platform server as well as Context Graph models. When upgrading, you need to upgrade your models in addition to upgrading the Spectrum Technology Platform server.

The upgrade process consists of these steps:

Back up your models and properties files.
On the master server, upgrade Spectrum Technology Platform then upgrade your models.
On each non-master server, upgrade Spectrum Technology Platform then copy the upgraded models from the master server to the non-master server.

To upgrade a cluster that runs Context Graph, follow this procedure:

Back up the server. For instructions on creating a backup, see the Administration Guide.

Important: We recommend that you create a backup before upgrading so that you can recover your flows, security settings, and other settings, if an error occurs during the upgrade process.
Open the Relationship Analysis Client and click Manage. Select the model you want to back up then click Backup.
In addition to backing up your models, back up these two property files:
- SpectrumFolder\server\modules\hub\hub.properties
- SpectrumFolder\server\modules\hub\db\neo4j.properties
Identify which node is the serving as the master server for Context Graph.
1. Open a web browser and go to:
  
  http://LoadBalancer:8080/jmx-console/HttpAdaptor/list
2. Scroll down to the neo4j.org domain.
  
  You will see a set of objects for each model. The Role attribute in the HighAvailability object indicates whether a server is the master for a model.
3. If you have more than one model and each model has a different master, you need to make one server the master of all the models. To do this, restart the cluster then open the Relationship Analysis Client using the hostname or IP address of one of the nodes rather than the load balancer. In the Relationship Analysis Client, open each model by running a query on each model. This will make the server you are connected to the master for each model.
Stop each non-master node in the cluster; stop the master server last. Stop nodes one at a time rather than all at once.

Important: Make sure that Spectrum Technology Platform stops without errors. If a server does not stop properly, Context Graph models on the server will not open successfully after upgrading. To ensure that Spectrum Technology Platform stopped cleanly, examine the SpectrumFolder\server\logs\spectrum-server.log file for errors during shutdown.
Upgrade the master server.
1. If you are upgrading from Spectrum Technology Platform 12.0 or later, each model directory must contain a version.data file. Review all the model.ModelName subdirectories located under SpectrumFolder\server\modules\hub\db to confirm that they contain a version.data file. If any model directory is missing this file, copy the corresponding version.data file from one of the non-master nodes.
2. Important: The installer will prompt you to start Spectrum Technology Platform after the installation completes. You must disable this option so that the server does not start automatically when the installation completes.
  Run the Spectrum Technology Platform installer to upgrade the master server to the new version of Spectrum Technology Platform.
3. Open the file SpectrumFolder\server\modules\hub\hub.properties in an editor and confirm that the following property is set to embedded:
```
hub.neo4j.database.type=embedded
```
4. Open the file SpectrumFolder\server\modules\hub\db\neo4j.properties in an editor and set the following property to true.
```
dbms.allow_upgrade=true
```
5. Start the Spectrum Technology Platform server.
6. Open each model in the Relationship Analysis Client and run a query. Any query is sufficient.
7. Stop the Spectrum Technology Platform server.
8. Indexed properties are now restricted to a maximum length of 4036 bytes. If your model has an indexed property that exceeds this limitation, proceed to step 6.
  If your model does not have an indexed property that exceeds this limitation, continue with substep 5.i.
9. Open the SpectrumFolder\server\modules\hub\hub.properties file in an editor and set the following properties:
```
hub.neo4j.database.type=ha
hub.servers.per.cluster=must be set to number of servers in the cluster
```
10. Compare any properties files that you backed up to the installed files and make any necessary changes. Do not overwrite new files with old files because new files may contain properties that old files do not.
11. Skip step 6 and continue to step 7.
Indexed properties are now restricted to a maximum length of 4036 bytes. If a model has an indexed property that exceeds this limitation, you will not be able to open that model until you complete the following steps:
1. Copy the SpectrumFolder\server\modules\hub\db\neo4j.properties file to the SpectrumFolder\server\modules\hub\db\model.ModelName folder for each model that exceeds the property constraint of 4036 characters.
2. Open the neo4j.properties files that you copied in Step a. In a text editor, uncomment and set dbms.index.default_schema_provider to lucene+native-1.0. Make sure the neo4j store upgrade is uncommented and that the following property is set to true:
```
dbms.allow_upgrade=true
```
3. Start the Spectrum Technology Platform server.
4. Remove the SpectrumFolder\server\modules\hub\db\model.ModelName\neo4j.properties file in each model folder that had the constraint.
  After you remove the files, native-btree-1.0 indexing will be used by default. We recommend that you fix all models that failed upgrade due to the 4036 indexed property constraint and re-index those models from Lucerne+native-1.0 indexes to the latest native-btree-1.0 indexes. See the hub model reindex command in the Administration Utility section of the Administration Guide.
5. Stop the Spectrum Technology Platform server.
6. Open the SpectrumFolder\server\modules\hub\hub.properties file in an editor and set the following property to ha:
```
hub.neo4j.database.type=ha
```
7. Set hub.servers.per.cluster to the number of servers in the cluster.
8. Compare any properties files that you backed up to the installed files and make any necessary changes. Do not overwrite new files with old files because new files may contain properties that old files do not.
Upgrade the non-master servers.
1. Delete the models in the SpectrumFolder\server\modules\hub\db directory.
  
  Warning: Do not delete the models from the master server.
2. Important: The installer will prompt you to start Spectrum Technology Platform after the installation completes. You must disable this option so that the server does not start automatically when the installation completes.
  On one of the non-master servers, run the Spectrum Technology Platform installer to upgrade it to the new version of Spectrum Technology Platform.
3. Open the SpectrumFolder\server\modules\hub\hub.properties file in an editor and confirm that the following properties are set:
```
hub.neo4j.database.type=ha
hub.servers.per.cluster=must be set to number of servers in cluster
```
4. Compare any properties files that you backed up to the installed files and make any necessary changes. Do not overwrite new files with old files because new files may contain properties that old files do not.
5. Copy all SpectrumFolder\server\modules\hub\db\model.ModelName directories from the master server to the non-master server.
6. Repeat these steps for each non-master server in the cluster.
Start all nodes in the cluster consecutively after upgrading.
1. Make sure that you start node 2 within only a few seconds after starting node 1, and repeat this for each remaining node.
2. Ensure that each server in the cluster is functioning. Check SpectrumFolder\server\logs\spectrum-server.log for any errors.
3. While directly connected to the master server (bypassing the load balancer), open each model, one at a time, and inspect the spectrum-server.log file for errors.