Installing Transformer

This page explains how to install an instance of Transformer using the Caplin Deployment Framework.

For instructions on upgrading and existing installation of Transformer, see Upgrading Transformer.

Support for Transformer 6.2 ended 17 January 2019. For Transformer 6.2 installation instructions, see Installing Transformer 6.2).

Requirements

Transformer 7 has the following requirements:

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

Additional requirements for Caplin Support

The following additional requirements increase the speed at which Caplin Support can diagnose issues in production and test environments:

  • System clock: UTC

  • Core dumps: set to unlimited size for all user accounts that run Caplin components

  • Java garbage collection logging: enabled for all active JVMs on the Caplin Platform

  • Red Hat packages: gdb (the GNU Debugger)

For instructions on setting up the additional requirements, see Getting information about a failed Platform component: Prerequisites.

Deploying Transformer

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

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

  2. Stop all running Caplin Platform components:

    $ ./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. When Transformer runs under an evaluation licence, Transformer shuts down after 30 minutes.
  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 hosts the Deployment Framework command dfw start will start Transformer:

    Example: dfw start starts Transformer if hostname matches 'transformer1.example.com' or 'transformer2.example.com'
    $ ./dfw hosts Transformer transformer1.example.com transformer2.example.com
    Example: dfw start starts Transformer on any host (use this for a local development environment only)
    $ ./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

    2. In the /etc/security/limits.conf file, set the core file size limit for the user account that runs Transformer to unlimited. 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
  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:

      jvm-options -Xloggc:var/gc.log
      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: