Upgrading Transformer

The page provides instructions on upgrading an existing installation of Transformer, and should be read in conjunction with Installing Transformer.

If you are upgrading from Transformer 6.2 to Transformer 7, see Upgrading to Caplin Platform 7.

Contents:

Requirements
Upgrade Transformer
Upgrade a Transformer Module

Requirements

Transformer 6.2 must be deployed on Deployment Framework 6.2.

Transformer 7 must be deployed on Deployment Framework 7.

Upgrade Transformer

You cannot use these instructions to upgrade Transformer 6.x to Transformer 7. See Upgrading to Caplin Platform 7.

To upgrade an existing installation of Transformer, follow the instructions below.

Read the release notes for the new version of Transformer and all versions in between the currency deployed version and the new version. Take note of any extra upgrade steps.

To find the version number of the installed blade, run the ./dfw versions command.
Stop all running Caplin Platform components:
```
$ ./dfw stop
```
Copy the new Transformer installation kit to the Deployment Framework’s kits directory.

Deploy the new kit:

Example upgrade: Transformer 7.1.3 to Transformer 7.1.5

$ ./dfw deploy

  Deploying Transformer kit Transformer-7.1.5-312996-x86_64-pc-linux-EL6-gnu.tar.gz
  Kit will be saved in kits/archive.
  Remove unpacked kit directory - Transformer-7.1.3-311854 (y/n) ? n (1)
  Kit successfully unpacked.
  Not copying license from Transformer kit. Ensure the current license
   is the same version as the kit just deployed.
  Not copying override file autopub.conf from kit. (2)
  Not copying override file cluster.conf from kit.
  Not copying override file java.conf from kit.
  Not copying override file jmx.conf from kit.
  Not copying override file pipeline.conf from kit.
  Not copying override file transformer.conf from kit.

  Please review the Transformer release note and merge these files if required.

  Inactive overrides exist for PersistenceService in the directory:

        global_config/inactive_overrides/PersistenceService

  Not copying kit overrides from PersistenceService blade in Transformer kit

  Please review the Transformer release note and merge the files in these
   directories if required.

  Transformer kit has deployed a new blade: TransformerSystemInfo

  1 kit(s) deployed

  Blades ok

1	The Deployment Framework prompts you to remove the previously unpacked kit directory (`kits/<blade_name>/<blade_name>-<version>`). Removing the unpacked kit directory does not remove the blade’s override files copied to `global_config/overrides/<blade_name>`.
2	Override files from the new version of the blade are not copied to the directory `global_config/overrides/<blade_name>` if they would overwrite existing files in that directory.

Check the blade installed correctly by listing all installed blades and their versions:
```
$ ./dfw versions
```

Check if there have been any changes introduced to the override files in the new version of the blade. Manually merge any changes to the override files under the global_config/overrides/<blade_name> directory.

To check for changes to override files between versions of a blade, download the installation kits for both versions, unpack the kits, and use the diff command to compare override directories.

$ tar xzf Transformer-7.1.3-311854-x86_64-pc-linux-EL6-gnu.tar.gz
$ tar xzf Transformer-7.1.5-312996-x86_64-pc-linux-EL6-gnu.tar.gz
$ diff -u Transformer-7.1.3-311854/etc/overrides/etc \
> Transformer-7.1.5-312996/etc/overrides/etc

If the diff output reveals that a new configuration item has been introduced, check the blade’s release notes for guidance on its use before copying the configuration item to the appropriate file under the global_config/overrides/<blade_name> directory.

Example diff output

diff -u Transformer-7.1.3-311854/etc/overrides/etc/java.conf Transformer-7.1.5-312996/etc/overrides/etc/java.conf
--- Transformer-7.1.3-311854/etc/overrides/etc/java.conf	2018-09-24 09:34:19.000000000 +0100
+++ Transformer-7.1.5-312996/etc/overrides/etc/java.conf	2019-05-14 13:46:12.000000000 +0100
@@ -4,8 +4,8 @@


 # The size of the Java heap (in megabytes)
-define JVM_XMS_HEAP_SIZE        256
-define JVM_XMX_HEAP_SIZE        256
+define TRANSFORMER_JVM_XMS_HEAP_SIZE        256
+define TRANSFORMER_JVM_XMX_HEAP_SIZE        256

 # If set to a non-zero value, then the JVM debugger will be started on the
 # configured port
@@ -20,7 +20,7 @@
 ## Java Heap size #############################################################
 #
 #
-jvm-options    -Xms${JVM_XMS_HEAP_SIZE}m -Xmx${JVM_XMX_HEAP_SIZE}m
+jvm-options    -Xms${TRANSFORMER_JVM_XMS_HEAP_SIZE}m -Xmx${TRANSFORMER_JVM_XMX_HEAP_SIZE}m


 ## Debugging options #########################################################

In the example diff output above, the JVM_XMS_HEAP_SIZE and JVM_XMX_HEAP_SIZE configuration variables have been renamed to TRANSFORMER_JVM_XMS_HEAP_SIZE and TRANSFORMER_JVM_XMX_HEAP_SIZE respectively. Merge these changes manually to the file global_config/overrides/servers/Transformer/java.conf, and update the file global_config/environment.conf if it references the old variable names.

The override files for Liberator 6 and Transformer 6 were packaged with the Deployment Framework 6. From Liberator 7 and Transformer 7, the override files are packaged in the etc/overrides/etc directories of the Liberator and Transformer deployment kits .

Restart Caplin Platform components:
```
$ ./dfw start
```

Upgrade a Transformer Module

You cannot use these instructions to upgrade a module from version 6.2 to 7. See Upgrading to Caplin Platform 7.

Before upgrading a module to a new version, check the release notes to confirm that the new version is compatible with the other components in your deployment.

To upgrade a Transformer module, follow the instructions below.

Stop all components running under the Deployment Framework:
```
$ ./dfw stop
```
Copy the module installation file to <Framework-root>/kits

Deploy the new version of the module:

Example upgrade: Refiner 7.0.1 to Refiner 7.1.0

$ ./dfw deploy

   Deploying CPB_RefinerService kit CPB_RefinerService-7.1.0-184-5068281.zip
   Kit will be saved in kits/archive.
   Remove unpacked kit directory - CPB_RefinerService-7.0.1-158-b2bd53d (y/n) ? n (1)
   Kit successfully unpacked.

   Already active: RefinerService

   Consult RefinerService release note and merge overrides from
   kits/CPB_RefinerService/Latest/overrides/RefinerService to
   global_config/overrides/RefinerService. (2)

   Copying the JTM library, jtm_DS5.so, from the Transformer kit to the
   RefinerService blade

   1 kit(s) deployed

   Blades ok

1	The Deployment Framework prompts you to remove the previously unpacked kit directory (`kits/<blade_name>/<blade_name>-<version>`). Removing the unpacked kit directory does not remove the blade’s override files copied to `global_config/overrides/<blade_name>`.
2	Override files from the new version of the blade are not copied to the directory `global_config/overrides/<blade_name>` if they would overwrite existing files in that directory.

Confirm the new version of the module has deployed correctly:
```
$ ./dfw versions
```
Check if there have been any changes introduced to the override files in the new version of the blade. Manually merge any changes to the override files under the global_config/overrides/<blade_name> directory.

To check for changes to override files between versions of a blade, download the installation kits for both versions, unpack the kits, and use the diff command to compare override directories.
```
$ tar xzf CPB_RefinerService-7.0.1-158-b2bd53d-x86_64-pc-linux-EL6-gnu.tar.gz
$ tar xzf CPB_RefinerService-7.1.0-184-5068281-x86_64-pc-linux-EL6-gnu.tar.gz
$ diff CPB_RefinerService-7.0.1-158-b2bd53d/overrides/RefinerService \
> CPB_RefinerService-7.1.0-184-5068281/overrides/RefinerService
```
If the diff output reveals that a new configuration item has been introduced, check the blade’s release notes for guidance on its use before copying the configuration item to the appropriate file under the global_config/overrides/<blade_name> directory.
Restart Caplin Platform components:
```
$ ./dfw start
```