# Deploying FX Professional

This page provides an overview of the steps for deploying FX Professional.

## Requirements

See [FX Professional system requirements](fx-professional-system-requirements.md#deployment).

## Install Tomcat

Download the latest version of [Apache Tomcat 9](https://tomcat.apache.org/download-90.cgi) and extract the files to your desired directory.

For more information on installing Tomcat 9, see [Tomcat Setup](https://tomcat.apache.org/tomcat-9.0-doc/setup.html) on the Tomcat website, and [RUNNING.txt](https://github.com/apache/tomcat/blob/9.0.x/RUNNING.txt) distributed with Tomcat.

## Deploy the FX Professional WAR file 

Follow the steps below: 

1. Shut down Tomcat.
2. Delete all files and subdirectories in your `<tomcat_root>/webapps` directory.

   ```plantuml
   @startsalt
   {
   {T
    + <color:goldenrod><size:15><&folder></size></color> apache-tomcat-//version//
    ++ <color:goldenrod><size:15><&folder></size></color> webapps
   }
   }
   @endsalt
   ```
3. Download the WAR file for your variant of FX Professional (`__variant__trader-__version__.war`) from the [Caplin Downloads](https://account.caplin.com/account/downloads/) website.
4. Copy the WAR file to your Tomcat webapps directory: `<tomcat_root>/webapps`.

   ```plantuml
   @startsalt
   {
   {T
    + <color:goldenrod><size:15><&folder></size></color> apache-tomcat-//version//
    ++ <color:goldenrod><size:15><&folder></size></color> webapps
    +++ <color:cornflowerblue><size:15><&file></size></color> **//variant//trader-3.31.0-1234.war**
   }
   }
   @endsalt
   ```
5. Remove the version information from the file name of the WAR file. For example, `__variant__trader-3.31.0-12345.war` becomes `__variant__trader.war`:

   ```plantuml
   @startsalt
   {
   {T
    + <color:goldenrod><size:15><&folder></size></color> apache-tomcat-//version//
    ++ <color:goldenrod><size:15><&folder></size></color> webapps
    +++ <color:cornflowerblue><size:15><&file></size></color> **//variant//trader.war**
   }
   }
   @endsalt
   ```
6. Create a web application context file `<tomcat_root>/conf/Catalina/localhost/__variant__trader.xml` with the following content:

   ```xml
   <?xml version='1.0' encoding='utf-8'?>

   <Context>

     <!-- Default set of monitored resources -->
     <WatchedResource>WEB-INF/web.xml</WatchedResource>

     <!-- Map URI '/resources' to directory '../conf/resources' -->
     <Resources>
       <PostResources className="org.apache.catalina.webresources.DirResourceSet"
       base="../conf/resources" webAppMount="/resources" />
     </Resources>

     <!-- Core JNDI configuration -->
     <Environment name="LIBERATOR.DOMAIN" value="example.com" ①
       type="java.lang.String" override="false" />
     <Environment name="LIBERATOR.PRIMARY.ADDRESS" value="lib1.example.com" ②
       type="java.lang.String" override="false" />
     <Environment name="LIBERATOR.PRIMARY.PORT" value="80"
       type="java.lang.String" override="false" />
     <Environment name="LIBERATOR.PRIMARY.HTTPS.PORT" value="443"
       type="java.lang.String" override="false" />
     <Environment name="LIBERATOR.SECONDARY.ADDRESS" value="lib2.example.com" ③
       type="java.lang.String" override="false" />
     <Environment name="LIBERATOR.SECONDARY.PORT" value="80"
       type="java.lang.String" override="false" />
     <Environment name="LIBERATOR.SECONDARY.HTTPS.PORT" value="443"
       type="java.lang.String" override="false" />
     <Environment name="CAPLIN.DEV.MODE" value="false" ④
       type="java.lang.String" override="false" />
     <Environment name="CAPLIN.LOGIN.ENABLED" value="true" ⑤
       type="java.lang.String" override="false" />
     
   </Context>
   ```
   1. Set [`LIBERATOR.DOMAIN`](fxpro-jndi-configuration.md#liberator-domain) to your domain
   2. Set [`LIBERATOR.PRIMARY.ADDRESS`](fxpro-jndi-configuration.md#liberator-primary-address) to the hostname of your primary Liberator
   3. Set [`LIBERATOR.SECONDARY.ADDRESS`](fxpro-jndi-configuration.md#liberator-secondary-address) to the hostname of your secondary Liberator
   4. Set [`CAPLIN.DEV.MODE`](fxpro-jndi-configuration.md#caplin-dev-mode) to `false` in production deployments
   5. Set [`CAPLIN.LOGIN.ENABLED`](fxpro-jndi-configuration.md#caplin-login-enabled) to `true` to use FX Professional’s built-in login page

      For more information on FX Professional’s JNDI environment entries, see [FX Professional JNDI configuration](fxpro-jndi-configuration.md).
7. Review FX Professional’s default HTTP headers configured in the WAR file’s `web.xml` file. For recommended headers, see [Recommended HTTP headers](recommended-http-headers.md). For instructions on how to override the default HTTP headers, see [Setting HTTP headers](setting-http-headers.md).

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

   To view the default HTTP headers set in the `web.xml` file, use the following command:

   ```
   $ unzip -p __variant__trader-__version__.war WEB-INF/web.xml | less
   ```
   </dd></dl>
8. Create a new folder `<tomcat_root>/conf/resources/`.
9. If you have licensed FX Professional’s Trade Confirmations feature, then add your `TermsAndConditions.__locale__.txt` files to the `<tomcat_root>/conf/resources/` folder.

   ```plantuml
   @startsalt
   {
   {T
    + <color:goldenrod><size:15><&folder></size></color> apache-tomcat-//version//
    ++ <color:goldenrod><size:15><&folder></size></color> conf
    +++ <color:goldenrod><size:15><&folder></size></color> resources
    ++++ <color:cornflowerblue><size:15><&file></size></color> **TermsAndConditions<locale>.txt**
   }
   }
   @endsalt
   ```
10. If you have licensed FX Professional’s Money Markets feature, then add your `MMTermsAndConfitions.__locale__.txt` files to the `<tomcat_root>/conf/resources/` folder.

   ```plantuml
   @startsalt
   {
   {T
    + <color:goldenrod><size:15><&folder></size></color> apache-tomcat-//version//
    ++ <color:goldenrod><size:15><&folder></size></color> conf
    +++ <color:goldenrod><size:15><&folder></size></color> resources
    ++++ <color:cornflowerblue><size:15><&file></size></color> **MMTermsAndConditions<locale>.txt**
   }
   }
   @endsalt
   ```

## Deploy the Webcentric database

The Webcentric database is used by the Webcentric servlet to persist users' customisations to FX Professional’s layout.

### Production deployments

For production deployments, Caplin provide schemas for a variety of database servers. Please speak to your Caplin account manager.

Follow the steps below:

1. Deploy the Webcentric schema to your production database server.
2. Add a `<Resource.../>` tag for your Webcentric database to the `<tomcat_root>/conf/Catalina/localhost/__variant__trader.xml` file.

   **Example: a MySQL database called 'webcentric' on host db.example.com**

   ```xml
   <Resource name="jdbc/mysqldb"
       auth="Container"
       type="java.sql.DataSource"
       username="webcentric_servlet"
       password="JP9DGnKUgn58FXhX"
       driverClassName="com.mysql.jdbc.Driver"
       url="jdbc:mysql://db.example.com:3306/webcentric"/>
   ```

   The values for tag attributes `username`, `password`, `driverClassName`, and `url` are under your control. Change them to values appropriate to your Webcentric database deployment.
3. Schedule regular backups of the Webcentric database. 

### Development deployments 

For development deployments, Caplin provide an example H2 database, packaged as `webcentric-db-__version__.zip`.

Follow the steps below:

1. Extract `webcentric-db-__version__.zip` to your Tomcat root directory.

   ```plantuml
   @startsalt
   {
   {T
    + <color:goldenrod><size:15><&folder></size></color> apache-tomcat-//version//
    ++ <color:goldenrod><size:15><&folder></size></color> webcentric-db
    +++ <color:goldenrod><size:15><&folder></size></color> //variant//trader
    ++++ <color:cornflowerblue><size:15><&file></size></color> **//variant//trader.h2.db**
   }
   }
   @endsalt
   ```
2. Add a `<Resource.../>` tag for the H2 database to the `<tomcat_root>/conf/Catalina/localhost/varianttrader.xml` file:

   ```xml
   <Resource name="jdbc/webcentricdb"
       auth="Container"
       type="javax.sql.DataSource"
       username="sa"
       password=""
       driverClassName="org.h2.Driver"
       url="jdbc:h2:../webcentric-db/varianttrader/varianttrader;IFEXISTS=TRUE;AUTO_SERVER=TRUE"/>
   ```

## Configure the Keymaster servlet

Follow the steps below to configure the Keymaster servlet:

1. Generate a new key pair for the web application’s Keymaster servlet:

   ```bash
   #!/bin/bash

   # PKCS1 private key. Compatible with KeyMaster.NET.
   openssl genrsa -out privatekey_pkcs1.pem 2048

   # Convert PKCS1 private key to PKCS8. Compatible with KeyMaster Java.
   openssl pkcs8 -topk8 -inform PEM -outform PEM -nocrypt -in privatekey_pkcs1.pem -out privatekey.pem

   # Export public key. Compatible with Caplin Liberator.
   openssl rsa -pubout -outform DER -in privatekey_pkcs1.pem -out keymaster_public.der
   ```
2. Copy the file `privatekey.pem` to `<tomcat_root>/conf/keymaster/`. 
3. Set the location of the private key in the `<tomcat_root>/conf/Catalina/localhost/__variant__trader.xml` file:

   ```xml
   <!-- KeyMaster servlet configuration -->
   <Environment name="caplin.keymaster.privatekey.filename" 
       value="../../conf/keymaster/privatekey.pem" 
       type="java.lang.String" override="false" />
   ```
4. Copy the file `keymaster_public.der` to the Deployment Framework directory `global-config/ssl` on all Liberator hosts.

## Configure the SignOn servlet

If your deployment uses FX Professional’s built-in sign in page (see [CAPLIN.LOGIN.ENABLED](fxpro-jndi-configuration.md#jndi-environment-entries) in FX Professional’s JNDI configuration), follow the steps below:

1. Generate a new key pair for the SignOn servlet. 

   ```bash
   #!/bin/bash

   # PKCS1 private key. 
   openssl genrsa -out privatekey_pkcs1.pem 2048

   # Convert PKCS1 private key to PKCS8. 
   openssl pkcs8 -topk8 -inform PEM -outform PEM -nocrypt -in privatekey_pkcs1.pem -out privateSignonKey.pem

   # Export public key. 
   openssl rsa -pubout -outform PEM -in privateSignonKey.pem -pubout -out publicSignonKey.pem
   ```
2. Copy both `privateSignonKey.pem` and `publicSignonKey.pem` to `<tomcat_root>/conf/signon/`.
3. Set the location of the new keys in the `<tomcat_root>/conf/Catalina/localhost/__variant__trader.xml` file:

   ```xml
   <Environment 
       name="caplin.signon.privatekey.filename" 
       value="../../conf/signon/privateSignonKey.pem" 
       type="java.lang.String" 
       override="false"/>
   <Environment 
       name="caplin.signon.publickey.filename" 
       value="../../conf/signon/publicSignonKey.pem" 
       type="java.lang.String" 
       override="false"/>
   ```

## Start Tomcat

If you start Tomcat manually, run the command below from Tomcat’s bin directory:

```
$ ./startup.sh
```

If you start Tomcat as a service, follow instructions in [RUNNING.txt](https://github.com/apache/tomcat/blob/main/RUNNING.txt).

You can now access FX Professional on http://__tomcat_host__:__tomcat_port__/__variant__trader.