Installing Transformer

This page explains how to install an instance of Transformer, using the Caplin Deployment Framework. Usually, this will be done as part of a wider process, and if you’ve installed Liberator, then you’ll have already completed some of the steps described. That said, we’re going to treat installing Transformer as if it were a stand-alone task, and won’t take anything for granted. However, you would typically use a Transformer in conjunction with Liberator.

In the following steps you’ll be using the dfw command of the Deployment Framework. Before entering any dfw command as ./dfw <command-name>, make sure your current (working) directory is set to the Deployment Framework’s topmost directory.

For a list of dfw commands, click here.

Download and install Cygwin

The Caplin Deployment Framework is operated from a command line, using Bash commands. If you’re running it on Windows therefore, you’ll need to download a Bash-compatible command line interface; we recommend Cygwin. Any time we refer to the command line in this tutorial, if you are using Windows, you can assume that we mean Cygwin.

It can be a bit tricky to install Cygwin so it has the correct packages needed to run the Deployment Framework. If you’ve never done it before, here are some detailed instructions.

You must install the following minimum set of Cygwin packages:

  1. unzip (from Archive)

  2. zip (from Archive)

  3. vim (from Editors)

  4. vim-common (from Editors)

  5. ncurses (from Utils)

Extract the Caplin Deployment Framework

If you haven’t done so already, download the Caplin Deployment Framework, and extract it to the desired directory. For details of how to do this, see Installing the Deployment Framework.

It’s quite likely that by the time you install Transformer, you’ll already have the Deployment Framework installed. If so, make sure it’s not running before you go any further.

To stop the Deployment Framework:

  • Navigate to the Deployment Framework’s topmost directory.

  • Enter the command: ./dfw stop

Set up the Transformer licence

If you don’t have a licence for your Transformer, you can still install and run it, but then the Transformer will run under a temporary evaluation licence and will shut down automatically after 30 minutes. You should replace this temporary licence as soon as possible with an authorised licence supplied by Caplin Systems.

Copy your licence file (license-transformer.conf) to the Deployment Framework’s licence directory:

<Framework-root>/global_config/licenses

You only need to copy licenses to the server machines on which the licensed Transformers run.

Copy the Transformer install file to the kits directory

Find the appropriate Transformer installation file, which will be a file called

Transformer-<VERSION_DETAILS>.type, where

  • .type is .tar.gz if the Transformer is to be installed on a Linux machine,

  • .type is .zip if the Transformer is to be installed on a Windows machine.

Copy the file into the kits directory of the Deployment Framework.

Deploy Transformer

Enter the command:

./dfw deploy

This unpacks Transformer and sets up any active built-in blades. It also automatically moves the installation file into the Deployment Framework’s kits/archive/ directory.

Check and merge Transformer configuration overrides

If you’re installing a new version of Transformer to replace an already installed version, you’ll most likely have modified and added to the configuration for the existing version. You should normally put such modifications in the Deployment Framework’s overrides directory for the Transformer:

<Framework-root>/global_config/overrides/Transformer

When you deploy the new Transformer kit, the ./dfw deploy command doesn’t remove or modify any existing configuration overrides. However, it will warn you if the new kit contains configuration overrides that clash with your existing overrides, and details the clashes.

If there are clashes, you should compare the configuration overrides in the new Transformer kit against the existing Transformer overrides as defined in <Framework-root>/global_config/overrides/Transformer, and merge any differences.

The release note for Transformer will detail any changes to configuration overrides in the kit.

Activate JMX Monitoring on Transformer

Once you’ve deployed Transformer, you can run it straight away if you want to. However, all Caplin’s server-side components are JMX-enabled, so that they can be monitored and managed using the Caplin Management Console (CMC), or another JMX client.

  • To activate JMX monitoring of Transformer using the TransformerJMX blade, enter the command:

    ./dfw activate TransformerJMX
    The TransformerJMX blade uses a Java Virtual Machine (JVM). If you see an error at this point, telling you that there is no JVM at the configured location, you’ll need to configure a JVM appropriately before JMX monitoring can be activated.

  • To check that the blade has been activated, enter the command:

    ./dfw versions

    and look for the TransformerJMX entry in the "Built-in blades" section of the displayed list.

  • To connect to the Transformer from a monitoring client, such as the CMC, you’ll need to know the RMI port and hostname. To find what these are, enter the command:

    ./dfw info

    Amongst the information displayed you’ll see a line like this:

    To monitor the Transformer connect the JMX monitoring tool to RMI port <port-number> on <hostname>

Start the Transformer

Now you can run Transformer:

  • If you haven’t got a Liberator installed, or you’ve got one and want to start it too,along with any other installed platform components, such as Integration Adapters, enter the command:

    ./dfw start

  • If you have got a Liberator installed, but don’t want it to be included in this simple test, enter the command:

    ./dfw start Transformer
    If you didn’t previously install an authorised license supplied by Caplin Systems, the Transformer will run under a temporary evaluation licence and will shut down automatically after 30 minutes.

  • Enter the command:

    ./dfw status

    You should see that the Transformer is now running.

  • You should also be able to view the Transformer’s status by monitoring it from a monitoring client such as the CMC.

…​and to stop it

  • To stop just the Transformer, leaving any other Platform components running, enter the command:

    ./dfw stop Transformer

  • To stop Transformer, Liberator and any other running Platform components, enter the command:

    ./dfw stop

See also: