# Installing Transformer This page explains how to deploy Transformer using the [Caplin Deployment Framework](../deployment-framework/index.md). For instructions on upgrading an existing deployment of Transformer, see [Upgrading Transformer](transformer-upgrading-transformer.md). ## 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)^{asterisk}^ | | 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](../platform-architecture/platform-hardware-and-software-requirements.md). ## Deploying Transformer Follow the steps below in the Deployment Framework for the host: 1. Ensure Transformer’s requirements are met. See [Requirements](#requirements) above. 2. Run the [`**dfw stop**`](../deployment-framework/cdf-the-deployment-framework-command-utility-dfw.md#stop) command to stop all components in the deployment: ```console $ ./dfw stop ``` 3. Copy your licence file for Transformer (`license_transformer.conf`) to the Deployment Framework’s `global_config/licenses` directory. **📌 NOTE**\ 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**`](../deployment-framework/cdf-the-deployment-framework-command-utility-dfw.md) command to deploy Transformer: ```console $ ./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**`](../deployment-framework/cdf-the-deployment-framework-command-utility-dfw.md#versions) command to confirm deployment and review which Transformer feature blades are active: ```console $ ./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**`](../deployment-framework/cdf-the-deployment-framework-command-utility-dfw.md#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'** ```console $ ./dfw hosts Transformer transformer1.example.com transformer2.example.com ``` **Example: Transformer runs on any deployment host (useful for local development deployments)** ```console $ ./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](https://access.redhat.com/solutions/61334) on the Red Hat website. 3. Install the Red Hat package for the GNU Debugger: ```console $ sudo yum install gdb ``` **📌 NOTE**\ The GNU Debugger tools are required by [Caplin Platform Diagnostics](https://github.com/caplin/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: ```console $ ./dfw deactivate TransformerDemoDataSource ``` 3. If you have purchased the [Caplin Management Console](../cmc/index.md) and you wish to monitor Transformer, follow the steps below: 1. Enable Transformer’s Java Management Extensions (JMX) interface. See [Activating JMX in Transformer](../cmc/activating-component-jmx-interface.md#transformer). 2. Change the JMX credentials from their default values. See [Activating JMX in Transformer](../cmc/activating-component-jmx-interface.md#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](../datasource/datasource-change-the-size-of-the-jvm-heap.md). **❗ IMPORTANT**\ 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](transformer-logging.md), [Logging in DataSource applications](../datasource/datasource-logging-in-datasource-applications.md), and [DataSource logging configuration](../datasource/datasource-logging-configuration.md). ## Starting and stopping Transformer Follow the steps below to confirm Transformer has installed correctly: 1. Run the [`**dfw start**`](../deployment-framework/cdf-the-deployment-framework-command-utility-dfw.md#start) command to start Transformer: ```console $ ./dfw start Transformer ``` 2. Run the [`**dfw status**`](../deployment-framework/cdf-the-deployment-framework-command-utility-dfw.md#status) command to check Transformer’s status is 'Running': ```console $ ./dfw status Core components Status Process ID ------------------------------------------------------------- Transformer Running 14779 Deployed Adapter blades Status Process ID ------------------------------------------------------------- ``` 3. Run the [`**dfw stop**`](../deployment-framework/cdf-the-deployment-framework-command-utility-dfw.md#stop) command to stop Transformer: ```console $ ./dfw stop Transformer ``` --- **See also:** * [Start and stop components and blades](../deployment-framework/cdf-start-and-stop-components-and-blades.md) * [Change server-specific configuration](../deployment-framework/cdf-change-server-specific-configuration.md) * [Set up server failover capability](../deployment-framework/cdf-set-up-server-failover-capability.md)