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.

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)

Java

OpenJDK 17

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

Deploying Transformer

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

  1. Ensure Transformer’s requirements are met. See Requirements above.

  2. Run the dfw stop command to stop all components in the deployment:

    $ ./dfw stop
  3. 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.
  4. Copy the Transformer deployment kit (archive ending in .tar.gz or .zip) to the Deployment Framework’s kits directory.

  5. 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
  6. 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
  7. 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
  8. 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:

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

    1. Set the system clock to UTC and synchronise with a time source common to all Caplin Platform servers.

    2. 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.

    3. 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.
  2. Deactivate unsecure feature blades:

    $ ./dfw deactivate TransformerDemoDataSource
  3. 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.

  4. 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
  5. 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:

  1. Run the dfw start command to start Transformer:

    $ ./dfw start Transformer
  2. 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
      -------------------------------------------------------------
  3. Run the dfw stop command to stop Transformer:

    $ ./dfw stop Transformer

See also: