# Installing Transformer

This page explains how to install an instance of **Transformer**, using the [**Caplin Deployment Framework**](../deployment-framework/index.md). Usually, this will be done as part of a wider process, and if you’ve installed [**Liberator**](../liberator/index.md), 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.

<dl><dt><strong>💡 TIP</strong></dt><dd>

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](../deployment-framework/cdf-the-deployment-framework-command-utility-dfw.md).
</dd></dl>

## 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_](https://www.cygwin.com). 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](https://cygwin.com/install.html).

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](../deployment-framework/cdf-installing-the-deployment-framework.md).

**📌 NOTE**\
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](../deployment-framework/cdf-the-deployment-framework-command-utility-dfw.md#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:

_&lt;Framework-root>/global_config/licenses_

**💡 TIP**\
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-&lt;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](../deployment-framework/cdf-built-in-blades.md). 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:

_&lt;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 _&lt;Framework-root>/global_config/overrides/Transformer_, and merge any differences.

**💡 TIP**\
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)](../cmc/index.md), or another [JMX](https://www.oracle.com/java/technologies/javase/javamanagement.html) client.

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

  ```
  ./dfw activate TransformerJMX
  ```

  **📌 NOTE**\
  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
  ```

  **📌 NOTE**\
  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:**

* [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)