# Deploying FX Sales

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

## Requirements

See [FX Sales system requirements](st-sales-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 Sales WAR file 

Follow the steps below:

1. Shut down Tomcat.
2. Delete all files and subdirectories in the `<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 Sales (`__variant__salestrader-__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//salestrader-//version//.war
   }
   }
   @endsalt
   ```
5. Remove the version information from the file name of the WAR. For example, `__variant__salestrader-2.20.0-12345.war` becomes `__variant__salestrader.war`. 
+ 
The directory now looks like this:

   ```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//salestrader.war
   }
   }
   @endsalt
   ```
6. Create a web application context file `<tomcat_root>/conf/Catalina/localhost/__variant__salestrader.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>

   <!-- 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`](st-jndi-configuration.md#liberator-domain) to your domain
   2. Set [`LIBERATOR.PRIMARY.ADDRESS`](st-jndi-configuration.md#liberator-primary-address) to the hostname of your primary Liberator
   3. Set [`LIBERATOR.SECONDARY.ADDRESS`](st-jndi-configuration.md#liberator-secondary-address) to the hostname of your secondary Liberator
   4. Set [`CAPLIN.DEV.MODE`](st-jndi-configuration.md#caplin-dev-mode) to `false` in production deployments
   5. Set [`CAPLIN.LOGIN.ENABLED`](st-jndi-configuration.md#caplin-login-enabled) to `true` to use FX Sales' built-in login page

      For more information on FX Sales' JNDI environment entries, see [FX Sales JNDI configuration](st-jndi-configuration.md).
7. Review FX Sales' 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 HTTP default 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>

## 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__salestrader.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 Sales' built-in sign in page (see [CAPLIN.LOGIN.ENABLED](st-jndi-configuration.md#jndi-environment-entries) in FX Sales' 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__salestrader.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 Sales on http://__tomcat_host__:__tomcat_port__/__variant__salestrader.