4. Preparing Your Environment

Before installing Uniphore Interact, the following key infrastructure applications need to exist in your environment:

Apache Web is recommended as the front-end for the application server.
Apache Tomcat to handle dynamic web applications.
MongoDB to handle the data tier.
Load Balancer to manage request traffic to server cluster members.

When using Single Node server architectures, these applications need to be installed on each node.

Apache Web Server Setup

It is recommended that on-premises installations use Apache web servers as the front end for the Interact application.

The web server component serves the following main roles:

Hold static content of the Interact clients (i.e., Mobile Web, Web Self Service, etc.)
Redirect requests to the Interact Server
Additional roles of the web server component can include:
- TLS/SSL handling (either by terminating TLS/SSL, or by communicating with the application servers using TLS/SSL)
- Supporting client-certificates for communication with the application server layer (2-way TLS/SSL)
For more details about setting up TLS/SSL configuration, click here here.
Limiting access to resources based on source of the request (e.g., blocking external users from accessing the Admin Console)
Manage load balancing among the application servers (when no load balancer exists)

Prior to beginning the installation, ensure that the latest Visual C++ 2012 x64 Redistributable Package is installed on all target node servers. You can download the package from https://www.microsoft.com/en-us/download/details.aspx?id=30679.

Installing the Apache Web Server

Windows O/S Installation

Note: It is recommended that you create a specific user for Apache. For more details, click here.

For Windows, download the Apache Web Server binary package that is appropriate for your Windows server version from https://httpd.apache.org/download.cgi and install according to the instructions provided.

Unzip the file to C:\Apache24

The following folder structure is expected:

Folder	Description
`C:\Apache24`	Root
`\conf`	Configuration file location. The main configuration file is `httpd.conf`
`\htdocs`	Location for static content
`\bin`	Executables

Windows users need to perform an additional configuration to set up a listening socket. For more details, click https://httpd.apache.org/docs/2.4/mod/core.html.

Linux O/S Installation

For Linux, download the Apache web server package from https://httpd.apache.org/download.cgi and install according to the instructions provided.

Installing the Interact Clients

The location for static content is defined by the DocumentRoot property in the httpd.conf file. The default value of this property points to the <Apache Root>\htdocs folder. All Interact clients should be located in \htdocs.

Each directory is also assigned a corresponding location in the httpd.conf file. For details on the options available for this directive, see https://httpd.apache.org/docs/2.4/mod/core.html#directory.

Reverse Proxy Configuration

Perform the following to redirect requests to the back-end server.

Note: For details about Apache proxy configurations, click here.

To enable proxying of requests to the Interact back-end, the following modules need to be installed:

LoadModule proxy_module modules/mod_proxy.so
LoadModule proxy_http_module modules/mod_proxy_http.so

After installing the modules, proxy all requests (path '/') to the back-end server by inserting the following configuration in the httpd.conf file:

ProxyPass / http://:/

To exclude Interact clients from the ProxyPass directive, add the following:

ProxyPass /mobileweb ! 
ProxyPass /agentapp ! 
ProxyPass /launchpad ! 
ProxyPass /webselfservice !

Using the exclamation point excludes the designated clients from the proxy configuration.

The following additional directives may be required for proper handling of requests:

ProxyPassCookieDomain
ProxyPassReverseCookieDomain
ProxyPreserveHost (preserves the original host of the request)

Blocking Access to Restricted Resources

Some resources handled by the web server are public facing, while others should be accessible to internal users only. For example, the Admin Console should only be accessible internally.

If a common web server must be used to handle both internal and external requests, it's recommended to block certain requests coming from external users. When it is not possible to do this using your organizational firewall or load balancer, access blocking can be done in the web server layer itself.

For details about blocking access to specific content based on the source of the request, refer to:

Handling TLS/SSL Requests to the Web Server

Note: The recommended setup for handling TLS/SSL requests to the Apache Web Server is to use an initial load balancer that terminates the TLS/SSL before they reach the Server. Using this setup will require no special server configuration.

When required, the Apache Web Server itself can handle inbound requests in TLS/SSL. In such a scenario, the Server needs to be configured to accept TLS/SSL and have a Server-side certificate:

The certificate and private key for the Web Server should be placed under <Apache Root>/conf/ssl.
By default, the TLS/SSL configuration is defined in <Apache Root>/conf/extra/httpd-ssl.conf. The main httpd.conf file configuration needs to point to this file.

To achieve this, make the following modifications in httpd.conf:

Enable the ssl module:

LoadModule ssl_module modules/mod_ssl.so

Verify that the httpd-ssl.conf is included:

<IfModule ssl_module> 
  Include conf/extra/httpd-ssl.conf 
  SSLRandomSeed startup builtin 
  SSLRandomSeed connect builtin 
  </IfModule>

For more details about TLS/SSL termination in the Web Server, see https://httpd.apache.org/docs/2.4/ssl/ssl_howto.html.

Proxying Requests to Application Servers using TLS/SSL

If you require proxy requests to the Application Server layer in TLS/SSL, use the following implementation:

Set up a TLS/SSL proxy in the Apache Web layer (as described above).
Set up a TLS/SSL connector on the Application Server by adding the following proxy setting to the httpd.conf file:
```
SSLProxyEngine on
```
Ensure that the Apache Web Server will perform TLS/SSL proxy certificate verification by adding the following setting to the httpd.conf file:
```
SSLProxyVerify require
```
Copy the relevant Application Server proxy certificate to the <Apache Root>/conf/ssl folder.
Instruct the Apache Web Server to trust the relevant proxy certificate by issuing the following command:
```
SSLProxyCACertificateFile "${SRVROOT}/conf/ssl/[relevant certificate filename]"
```

For more details about TLS/SSL proxy support in the Apache Web Server, see https://httpd.apache.org/docs/2.4/mod/mod_ssl.html#sslproxyengine.

Configuring GZIP Compression

To enable the Apache web server to handle GZIP compression, an output filter needs to be added. For details, click here.

Apache Tomcat Application Server Setup

Uniphore Interact uses Apache Tomcat to handle all dynamic web applications.

Installing Apache Tomcat

Note: The Interact Server now requires Tomcat Version 9.0.53.

Windows O/S Installation

For Windows, download the appropriate Apache Tomcat package from here and follow the instructions provided.

Linux O/S Installation

For Linux, download the appropriate Apache Tomcat package from here and follow the instructions provided.

Connecting Tomcat to Back-End Servers Using TLS/SSL

Security policies may require that the Tomcat Application Server to connect to back-end servers (e.g., CRM, IVR, etc.) using TLS/SSL. If back-end servers identify themselves with a self signed certificate, this certificate needs to be added to the Java trust store.

Note: Verify that you are working with the Java installation running the Tomcat instance.

Go to <java home>/bin and run the following command:
```
keytool -import -alias <alias> -keystore <cacerts_file> -trustcacerts -file <certificate_filename>
```
Where:
- alias - Is a value of your choice
- cacerts_file - The full path to the cacerts file: <java home>/lib/security/cacerts. Verify that the file is in place.
- certificate_filename - The full path to the back-end certificate file
When prompted for the password, enter the default password changeit.
When the Trust this certificate? prompt is displayed, enter Y and press to complete the certificate registration.

Instructing Tomcat to Terminate an HTTPS Communication

If you want Tomcat to listen for a HTTPS communication and terminate it, you need to create a connector for TLS/SSL in <tomcat>/conf/server.xml.

For example:

<Connector 
  port="443" minProcessors="5" maxProcessors="75" 
  enableLookups="true" disableUploadTimeout="true" 
  acceptCount="100" maxThreads="200" 
  scheme="https" secure="true" SSLEnabled="true"
  keystoreFile="WHOLE-PATH+PFX-NAME" 
  keystorePass="PFX-PASSWORD" 
  keystoreType="PKCS12" >

Where:

port - Points to the port to be used (generally 443)
keystoreFile - Provides the full path to the *.pfx certificate file. You can place the file in a location of your choice in the <tomcat> folder and point to it.
keystorePass - Sets the password for the certificate

For more details about TLS/SSL support in the Tomcat Application Server, see https://tomcat.apache.org/tomcat-9.0-doc/ssl-howto.html.

MongoDB Server Setup

Interact uses MongoDB to handle the data tier.

Note: The Interact Server now requires MongoDB Version 6.0.17.

Server Memory Settings

Upon installation of a new MongoDB node, open the mongod.conf file in the <MongoDB>\etcfolder of your Interact Server(s) and add the following parameters:

setParameter = internalQueryMaxAddToSetBytes=2097152000

setParameter = internalQueryMaxPushBytes=2097152000

When using YAML formatting, add the parameters as follows:

setParameter:

internalQueryMaxAddToSetBytes: 2097152000

internalQueryMaxPushBytes: 2097152000

Setup for High Availability

Setting up MongoDB for high availability requires setting up a MongoDB replica set.

For general information about MongoDB replication, go to https://docs.mongodb.org/manual/replication/.

For the guidance on creating the MongoDB replica set architecture, go to https://docs.mongodb.org/manual/replication/.

For step-by-step guidance on creating a replica set, go to: https://docs.mongodb.org/manual/tutorial/deploy-replica-set/.

Setup Validation Tips

To check the status of the replica set, use rs.Status() to verify that all members are connected.
To check whether the IP of each member is set correctly, use rs.config().

Sometimes the IP number for the primary member is not picked up correctly by MongoDB. Should this occur, you can set the host of each member. For more details, see https://docs.mongodb.org/manual/tutorial/change-hostnames-in-a-replica-set/.

MongoDB Security

MongoDB offers various options for restricting access to the database. It is best practice to limit access to the DB instance using standard firewall rules within the organization.

The current MongoDB version supports LDAP and SCRAM-SHA-256 authentication.

For details on advanced MongoDB security options, see https://docs.mongodb.org/manual/security/

Setting Up Sharding for MongoDB

Sharding is a method of storing data on multiple servers to provide scalability and improve performance when collections involve large data sets.

Enabling sharding in MongoDB distributes Interact data evenly across MongoDB replica sets.

Sharding makes read operations more efficient, since the Mongo server knows on which shard a relevant data component is stored. Similarly, since sort operations rely on natural ordering based on a sharded key, sorting the database is also quicker.

For general information about MongoDB sharding, go to https://docs.mongodb.com/manual/sharding/.

For step-by-step guidance on sharding, go to: https://docs.mongodb.com/manual/tutorial/deploy-shard-cluster/.

Enabling MongoDB Sharding for Interact

To enable sharding, a sharding-based key structure must be used for document identifiers in the database collection.

For Interact, every document identifier (i.e., objectId) in the Navigation collection uses the following structure: interactionInstanceId_runningSuffix , for example: p9XkKKY9_ab.

where:

interactionInstanceId is a unique identifier for a single Interaction invocation. All audit messages within the same Interaction instance have the same prefix.
runningSuffix is a running alphanumeric two-digit string beginning with aa.

The following shows a sequence of document identifiers from a single Interaction instance:

p9XkKKY9 (This is the START_INTERACTION message. It will always use the identifier interactionInstanceId, but without a suffix.)
p9XkKKY9_aa
p9XkKKY9_ab
…
p9XkKKY9_az
etc.

The following procedure will enable sharding for the Navigation collection on a database with an identifier of 5486ede1e14b788b5211ebb8.

Note: In an on-premise installation, the database identifier is identical to the tenant ID for the installation.

Add the database instance to a sharded cluster. From the console for the query router, run the command:
```
sh.enableSharding("5486ede1e14b788b5211ebb8")
```
Activate sharding for the specific collection, based on the sharded key. For the Navigation collection, run the following command:
```
sh.shardCollection("5486ede1e14b788b5211ebb8.Navigation", { "_id": 1 } )        
```
The Navigation collection will be automatically distributed among the shards in the cluster, according to its document identifier.
Verify the sharding setup. From the console for the Query Router, run the command:
```
db.printShardingStatus({verbose:true})
```
When sharding is correctly enabled, the status show for the database and the Navigation collection dislays as sharded.

For general information about setting up MongoDB shard keys, go to https://docs.mongodb.com/manual/core/sharding-shard-key/.

To ensure success, Interact Server(s) must be configured to work with Query Router servers, not directly with the shards, as described in MongoDB documentation.

Configuring LDAP Authentication for MongoDB

You set up MongoDB to perform authentication against Active Directory or LDAP credentials in two phases:

Configure the authentication service
Configure the Interact Server

The following procedures provide generic examples for LDAP authentication. For specific details related to your environment, consult your IT administrator and see MongoDB online documentation at https://docs.mongodb.com/v4.0/tutorial/authenticate-nativeldap-activedirectory/.

Note: This example explains how to configure LDAP Authentication using command line arguments. For details on how to configure using the MongoDB configuration file, see https://docs.mongodb.com/manual/reference/configuration-options/.

Configure the Interact Server

Configure the Interact Server to use LDAP authentication when connecting with MongoDB.

Stop the Tomcat service:
```
service tomcat stop
```
Add the following settings to both mongo.properties and the mongo-report.properties files, replacing the bracketed values with the username and password of the relevant Interact User:
```
mongo.auth=LDAP 
mongo.username=[interactuser] 
mongo.password=[LDAP Password]
```
Restart the Tomcat service:
```
service tomcat start
```

Configuring Internal Authentication for MongoDB

You set up MongDB to perform internal authentication in two phases:

Create required users
Configure the Interact Server

The following procedures provide generic examples for internal authentication. For specific details related to your environment, consult your IT administrator and see MongoDB online documentation.

Note: This example explains how to configure internal authentication using command line arguments. For details on how to configure using the MongoDB configuration file, see https://docs.mongodb.com/manual/reference/configuration-options/.

Restart MongoDB (1)

Starting (or restart) MongoDB with the following command:

/mongod --dbpath

For example:

/usr/bin/mongod --dbpath /var/lib/mongo1

Create Required Internal Users

Create credentials for users who will have credentials stored in MongoDB.

Generally, it is sufficient to create the following two users:

An Admin user who is able to create additional users. This user is required by MongoDB for administration on other databases.
Run the following command to add an Admin with username mongouseradmin:
```
use admin 
db.createUser({ 
  user : "mongouseradmin", 
  roles: [ {role:"userAdminAnyDatabase", db:"admin"}]
  })
```
A second user who has Read/Write privileges to Interact databases.
Run the following command to add an Interact user named interactuser:
```
use admin 
db.createUser({ 
  user : "interactuser", 
  roles: [ {role:"readWriteAnyDatabase", db:"admin"}]
  })
```

Restart MongoDB (2)

Restart MongoDB to initialize your new internal authentication.

For specific instructions for your environment, consult your IT administrator and refer to MongoDB online documentation.

Run the following command to restart MongoDB:

/mongod --dbpath --auth

For example:

/usr/bin/mongod --dbpath /var/lib/mongo1 --auth

Configure the Interact Server

Configure the Interact Server to use internal authentication when connecting with MongoDB.

Stop the Tomcat service:
```
service tomcat stop
```
Add the following settings to both mongo.properties and the mongo-report.properties files, replacing the bracketed values with the username and password of the relevant Interact User:
```
mongo.username=[interactuser] 
mongo.password=[Password]
```
Restart the Tomcat service:
```
service tomcat start
```

Configuring TLS/SSL Requests to MongoDB

You set up MongDB to handle TLS/SSL request in two phases:

Create a certificate
Configure Interact and Tomcat to work with the certificate

The following procedures provide generic examples for configuring TSL/SSL. For specific details related to your environment, consult your IT administrator and see MongoDB online documentation.

Note: This example explains how to configure TSL/SSL using command line arguments. For details on how to configure using the MongoDB configuration file, see https://docs.mongodb.com/manual/reference/configuration-options/.

Create and Integrate the TSL/SSL Certificate

Verify that the MongoDB service is stopped.

Create a certificate by running one of the following commands:

For Windows:

set OPENSSL_CONF=c:\OpenSSL-Win64\bin\openssl.cfg

For Linux:

openssl req -newkey rsa:2048 -new -x509 -days 365 -nodes -out [Crt File Name] -keyout [Key File Name]

Create a .pem file by running the following command:

cat [Key File Name] [Crt File Name] > [Pem File Name]

For example:

cat mongodb-cert.key mongodb-cert.crt > mongodb.pem

Integrate the new TLS/SSL .pem file with MongoDB using the following command:

mongod --sslMode requireSSL --sslPEMKeyFile [Pem File Path] --dbpath data

For example:

mongod --sslMode requireSSL --sslPEMKeyFile C:\OpenSSL-Win64\bin\mongodb.pem --dbpath data

Import the certificate to the Java trust store with the keytool service using the following command:

keytool -importcert -trustcacerts -file [Crt File Path] -keystore [JRE Key Store Path]

For example:

keytool -importcert -trustcacerts -file "C:\OpenSSL-Win64\bin\mongodb-cert.crt" -keystore "C:\Program Files\Java\jre7\lib\security\cacerts"

When prompted for the password, enter the default password changeit.

Configure Interact to Handle TLS/SSL

Stop the Tomcat service. For example:
```
service tomcat stop
```

Set up the Interact Server to handle TLS/SSL by adding required arguments to your JVM:

Enable editing of the Tomcat setenv.sh file with the following command:
```
edit /usr/local/tomcat/bin/setenv.sh
```

Add the following settings to the file:

-Djavax.net.debug=ssl 
-Dhttps.protocols=TLSv1,TLSv1.1,TLSv1.2 
-Djavax.net.ssl.trustStore=[JRE Key Store Path]

For example:

-Djavax.net.debug=ssl 
-Dhttps.protocols=TLSv1,TLSv1.1,TLSv1.2 
-Djavax.net.ssl.trustStore="C:\Program Files\Java\jre7\lib\security\cacerts"

Add the following settings to both mongo.properties and the mongo-report.properties files:
```
mongo.ssl.mode=true
```
Restart the Tomcat service. For example:
```
service tomcat start
```

Load Balancer Setup

A load balancer is required at the front-end of a typical Interact cluster configuration to maintain highest performance under any load conditions.

The load balancer becomes the single access point to the cluster and acts as the request distributor to all cluster members.

Configure the Load Balancer

Uniphore recommends using the F5 Network BIG-IP Local Traffic Management (LTM) system for directing traffic to the cluster members running Uniphore Interact.

The BIG-IP LTM configuration comprises the following components:

A virtual server that acts as the traffic manager.
A connection pool (a set of devices grouped together to receive traffic according to a load balancing method) that is associated with the virtual server.
Connection pool members (i.e., the Tomcat cluster members)

Runtime balancing affects all Interact traffic traveling between the client machines, the LTM virtual server and the cluster members.

BIG-IP LTM Configuration Settings

Use the BIG-IP LTM configuration utility to set the following properties and resources.

Setting	Required Value	Setting Location
`Default Persistence Profile`	`cookie`	Main Tab > Local Traffic > Virtual Servers > Virtual Server List > [virtual_server_name] Properties > Configuration > Advanced Properties Note: Session stickiness is required for the Interact Admin Console.
`HTTP Profile`	`http`	Main Tab > Local Traffic > Virtual Servers > Virtual Server List > [virtual_server_name] Properties > Configuration > Advanced Properties
`Protocol Profile` (Client) and `Protocol Profile` (Server)	Set both properties to the TCP profile of your choice. After assigning the TCP profile ensure that its Nagle’s Algorithm setting is not checked to prevent unnecessary TCP/IP delay of small packets during their routing.	Main Tab > Local Traffic > Virtual Servers > Virtual Server List > [virtual_server_name] Properties > Configuration > Advanced Properties
`SSL Profile` (Client)	`clientssl` This ensures that virtual server always used encrypted communications with client machines.	Main Tab > Local Traffic > Virtual Servers > Virtual Server List > [virtual_server_name] Properties > Configuration > Advanced Properties
Health Monitoring:
`Health Monitors` property in the Default Pool resource	Assign an active monitor of type TCP to this property. These settings tell the LTM how to monitor TCP connection status of application server pool members when balancing new connection requests to the server cluster.	Access the `Default Pool` resource via Main Tab > Local Traffic > Virtual Servers > Virtual Server List > [virtual_server_name] Resources > Load Balancing Resources Access the `Health Monitors` property via Main Tab > Local Traffic > Pools > Pool List > [pool_name] > Properties > Configuration > Basic Properties
`Interval` (for the assigned Health Monitors)	30 seconds	Main Tab > Local Traffic > Monitors > Monitor List > [monitor_name] > Properties > Configuration > Basic Properties
`Timeout` (for the assigned Health Monitors)	91 seconds	Main Tab > Local Traffic > Monitors > Monitor List > [monitor_name] > Properties > Configuration > Basic Properties

Sizing Calculation

To create these guidelines, Uniphore used performance tests based on the number of Flows handled by a call center, and the number of Flow steps sent by the Interact Server.

To estimate the number of Flows handled per day, consider the number of agents working in a call center and the number of hours/day that the center is active.

For example, let's assume that an agent is generally able to handle about 6 Flows in one hour, or 48 Flows in an eight-hour shift. Based on this formula, if a call center has 100 agents working one eight-hour shift, it can handle approximately 4,800 Flows per day.

To estimate the number of Flow steps sent by the Interact Server, it is possible to calculate that an average Flow has 30 steps (20 visual and 10 non-visual). Only the visual steps are sent from the Server.

After consideration of the above, use the following guidelines to estimate the required Storage Size and the Number of Servers to efficiently handle the traffic.

Note: When using Non-Audit capabilities, plan on using more Servers than indicated below. Contact Uniphore Support for additional sizing recommendations.

Estimating Cluster Size Based on Hit Rate

A single Server can safely handle 30 hits/second, which translates to ~6000 Flows per hour (i.e., 35 (hits/sec) * 3600 (sec) / 20 visual steps = 6300).
Handling a peak of 12,000 Flows per hour requires a minimum of 2 Server instances. To ensure high availability during peak hours, use 3 Servers. If your system will be handling peaks of more than 12,000 Flows per hour, multiply the number of Server instances accordingly.

Database Sizing

To ensure sufficient storage space for all database maintenance and troubleshooting processes, we recommend reserving at least 150 GB of storage, regardless of the level of Flow activity.

As a general rule, each step (visual or non-visual) requires an average of 3k of storage space.
A 30-step Flow requires ~100k of storage (i.e., 10k * 30 steps).
90 days of data retention requires ~45 GB (i.e., 5000 * 100K * 90), assuming 5000 Flows per day.
Storage is required for any participating member in the MongoDB replica set. Arbiter nodes do not require storage.

Replica Set Operations Log (Oplog) Sizing

The oplog is a rolling record log of all primary member database operations. In a replica set, secondary members copy the operations from the primary member and then apply the operations to their local data.

The oplog is a fixed-sized collection that automatically overwrites its oldest entries when it reaches its maximum size. Should a secondary member be taken down for an extended period of maintenance, the oplog can overwrite commands that the offline member has not yet replicated. In such a scenario, the offline member will require a complete resynchronization.

To help avoid this scenario, it is critical that an appropriate size be specified for the oplog. Use the following recommended guidelines:

Set the oplog size to support a minimum 48-hour maintenance window.
Assuming 5000 Flows per day (e.g., as described above), oplog size should be at least 10 GB for the 48-hour maintenance window.
By default, the size specified for the oplog is 5% of the free disk space on the MongoDB server.
For complete information about replica set oplog size, see https://docs.mongodb.com/manual/core/replica-set-oplog/.

In this section:

Uniphore Customer Portal

4. Preparing Your Environment

Apache Web Server Setup

Apache Tomcat Application Server Setup

MongoDB Server Setup

Load Balancer Setup

Search results