Installing Transformer

This page explains how to deploy Transformer using the Caplin Deployment Framework.

For instructions on upgrading an existing deployment of Transformer, see Upgrading Transformer.

Contents:

Requirements
Deploying Transformer
Additional steps for production and test deployments
Starting and stopping Transformer

Requirements

Transformer 8 has the following requirements:

Operating system	Red Hat Enterprise Linux 9 (x86_64, aarch64) [recommended] Red Hat Enterprise Linux 8 (x86_64) Red Hat Enterprise Linux 7 (x86_64)^*
Java	OpenJDK 17, 21

Operating system

Red Hat Enterprise Linux 9 (x86_64, aarch64) [recommended]
Red Hat Enterprise Linux 8 (x86_64)
Red Hat Enterprise Linux 7 (x86_64)^*

Java

OpenJDK 17, 21

^* Red Hat Extended Life Cycle Support subscription required from 30th June 2024

For suggested server hardware specifications, see Caplin Platform System Requirements.

Deploying Transformer

Follow the steps below in the Deployment Framework for the host:

Ensure Transformer’s requirements are met. See Requirements above.
Run the dfw stop command to stop all components in the deployment:
```
$ ./dfw stop
```

Copy your licence file for Transformer (license_transformer.conf) to the Deployment Framework’s global_config/licenses directory.

If you don’t have a licence file for Transformer, the Deployment Framework will copy an evaluation licence to the global_config/licenses directory on deployment of Transformer. Evaluation licenses permit only 30 minutes of continuous uptime and do not include options for charting, intraday-price recording, filtering, and the Persistence Service.

Copy the Transformer deployment kit (archive ending in .tar.gz or .zip) to the Deployment Framework’s kits directory.

Run the dfw deploy command to deploy Transformer:

$ ./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.
  Kit successfully unpacked.
  Not copying license from Transformer kit. Ensure the current license
   is the same version as the kit just deployed.

  Transformer kit has deployed a new blade: PersistenceService
  Transformer kit has deployed a new blade: PersistenceServiceClient
  Transformer kit has deployed a new blade: TransformerDemoDataSource
  Transformer kit has deployed a new blade: TransformerJMX
  Transformer kit has deployed a new blade: TransformerSystemInfo
  Transformer kit has deployed a new blade: TransformerToLiberatorConnection
  Transformer kit has deployed a new blade: TransformerToLiberatorSSLConnection

  Activating the peer connection blade.

  Activating TransformerToLiberatorConnection

  Blades ok

  The configuration has been updated. The new configuration will not be active
  until the Framework is restarted.

  1 kit(s) deployed

  Blades ok

Run the dfw versions command to confirm deployment and review which Transformer feature blades are active:

$ ./dfw versions

  Deployment Framework                     7.1.1-313146

  Core components                          Version
  ---------------------------------------------------------------------
  Transformer                              7.1.5-312996

  Deployed blades                          Version            State
  ---------------------------------------------------------------------
  PersistenceService                       7.1.5-312996       Inactive
  PersistenceServiceClient                 7.1.5-312996       Inactive
  TransformerDemoDataSource                7.1.5-312996       Inactive
  TransformerJMX                           7.1.5-312996       Inactive
  TransformerSystemInfo                    7.1.5-312996       Inactive
  TransformerToLiberatorConnection         7.1.5-312996       Active
  TransformerToLiberatorSSLConnection      7.1.5-312996       Inactive

Run the dfw hosts command to specify on which deployment hosts you want Transformer to run:
Example: Transformer runs only on deployment hosts 'transformer1.example.com' or 'transformer2.example.com'
```
$ ./dfw hosts Transformer transformer1.example.com transformer2.example.com
```
Example: Transformer runs on any deployment host (useful for local development deployments)
```
$ ./dfw hosts Transformer localhost localhost
```
Grant Transformer’s user account write permission to the following directories:
- Transformer’s log directory: servers/Transformer/var
- Transformer’s working directory: servers/Transformer

Additional steps for production and test deployments

Follow the additional steps below:

To improve the speed at which Caplin Support can diagnose issues with your deployment, make the following configuration changes to the host:

Set the system clock to UTC and synchronise with a time source common to all Caplin Platform servers.
For the Linux user that runs Transformer, set the soft and hard limits for the core resource to 'unlimited'. Core dumps provide valuable information for Caplin Support in the event of component failure. For more information on setting user limits, see How to set ulimit values on the Red Hat website.

Install the Red Hat package for the GNU Debugger:

$ sudo yum install gdb

The GNU Debugger tools are required by Caplin Platform Diagnostics, Bash scripts from Caplin Support that automate the collection of diagnostic data from a running or crashed Caplin component.

Deactivate unsecure feature blades:

$ ./dfw deactivate TransformerDemoDataSource

If you have purchased the Caplin Management Console and you wish to monitor Transformer, follow the steps below:
1. Enable Transformer’s Java Management Extensions (JMX) interface. See Activating JMX in Transformer.
2. Change the JMX credentials from their default values. See Activating JMX in Transformer.
If you have activated Transformer’s JMX interface or deployed any other blade that requires Transformer’s JVM, follow the steps below:
1. Set Transformer’s JVM heap size to 2048 megabytes, test against expected workloads, and increase the heap size if required. See Configure a DataSource application’s JVM.
  
  Transformer’s default JVM heap size (256MB) is not intended to handle production-level workloads.
2. Enable garbage collection (GC) logging for Transformer’s JVM. GC logs help Caplin Support diagnose the cause of application issues. Add the following configuration lines to the Deployment Framework file global_config/overrides/servers/Transformer/etc/java.conf:
  # Set the path and filename of the GC log. # Include the PID (%p) or date (%t) in the filename # to prevent the GC log from being overwritten # on restarting the DataSource. # # jvm-options -Xloggc:var/gc-%t.log jvm-options -Xloggc:var/gc-%p.log # GC logging options jvm-options -XX:+PrintGCDetails jvm-options -XX:+PrintGCDateStamps jvm-options -XX:+UseGCLogFileRotation jvm-options -XX:NumberOfGCLogFiles=10 jvm-options -XX:GCLogFileSize=5M jvm-options -XX:+PrintConcurrentLocks jvm-options -XX:+PrintCommandLineFlags jvm-options -XX:+HeapDumpOnOutOfMemoryError jvm-options -XX:HeapDumpPath=var
Configure Transformer’s log-cycling policy and provision disk space for log files. We recommend that you set the logging level to INFO and retain logs for 7 days. Cycle the Transformer’s packet log every 15-30 minutes, and cycle all other Transformer logs every 24 hours. For more information, see Transformer logging, Logging in DataSource applications, and DataSource logging configuration.

Starting and stopping Transformer

Follow the steps below to confirm Transformer has installed correctly:

Run the dfw start command to start Transformer:
```
$ ./dfw start Transformer
```

Run the dfw status command to check Transformer’s status is 'Running':

$ ./dfw status

  Core components                Status             Process ID
  -------------------------------------------------------------
  Transformer                    Running            14779

  Deployed Adapter blades        Status             Process ID
  -------------------------------------------------------------

Run the dfw stop command to stop Transformer:
```
$ ./dfw stop Transformer
```

See also: