PMF Analytics Receiver Server Installation Guide

Overview

PMF Analytics Receiver Server is implemented and shipped as Java EE standard web application archive (WAR) file. Therefore, it can be installed in any one of the following supported application servers: WebSphere Application Server Liberty, or Apache Tomcat (WAR files only).

Jump to

• Prerequisites to Run the Analytics
• System requirements
• Capacity considerations
• Installing Persistent Mobile Foundation Analytics Receiver on WebSphere Application Server Liberty
• Installing Persistent Mobile Foundation Analytics Receiver on Tomcat
• Installing Persistent Mobile Foundation Analytics Receiver with Ant tasks

System requirements

For complete set of system requirements please refer System Requirements page.

Hardware

• RAM: More RAM is better, but not more than 64 GB per node. 32 GB and 16 GB are also acceptable. Less than 8 GB requires many small nodes in the cluster, and 64 GB is wasteful and problematic due to the way Java uses memory for pointers.
• CPU: CPU tends not to be the performance bottleneck. Use systems with 2 to 8 cores.

Hardware configuration

• Give your JVM ample size to scale the in-memory queue with a size of 10000 (i.e., minimum Xmx as 6 GB).
• If you use BSDs and Linux, ensure that your operating system I/O scheduler is set to deadline or noop, not cfq.

Capacity considerations

Capacity is the single-most common question. How much RAM do you need? How much disk space? How many nodes? The answer is always subjective.

Persistent Mobile Foundation Analytics Receiver does not require disk space since it just receives logs from mobile applications and forwards them to analytics server, there is no storage of events data.

Installing Persistent Mobile Foundation Analytics Receiver on WebSphere Application Server Liberty

Ensure that you already have the Persistent Mobile Foundation Analytics Receiver WAR file. For more information on the installation artifacts, see Installing PMF to an application server. The analytics-receiver.war file is found in the <pmf_install_dir>\Analyticsreceiver folder. For more information about how to download and install WebSphere Application Server Liberty, see the About WebSphere Liberty article on IBM developerWorks .

1. Create a server by running the following command in your ./wlp/bin folder.

   ./server create <serverName>
   

2. Install features by running the following command from your ./bin folder.

   ./featureManager install jsp-2.2 ssl-1.0 appSecurity-1.0 localConnector-1.0
   

3. Add the analytics-receiver.war file to the ./usr/servers/<serverName>/apps folder of your Liberty Server.

4. Replace the contents of the **** tag of the `./usr/servers//server.xml` file with the following content:

   <featureManager>
        <feature>jsp-2.2</feature>
        <feature>ssl-1.0</feature>
        <feature>appSecurity-1.0</feature>
        <feature>localConnector-1.0</feature>
   </featureManager>
   

5. Configure analytics-receiver.war as an application with role-based security in the server.xml file. The following example creates a basic hardcoded user registry and assigns a user to each of the different analytics roles.

   <application id="analytics-receiver" name="analytics-receiver" location="analytics-receiver.war" type="war">
        <application-bnd>
            <security-role name="analytics_administrator">
                <user name="admin"/>
            </security-role>
            <security-role name="analytics_infrastructure">
                <user name="infrastructure"/>
            </security-role>
            <security-role name="analytics_support">
                <user name="support"/>
            </security-role>
            <security-role name="analytics_developer">
                <user name="developer"/>
            </security-role>
            <security-role name="analytics_business">
                <user name="business"/>
            </security-role>
        </application-bnd>
   </application>
   
   <basicRegistry id="worklight" realm="worklightRealm">
        <user name="business" password="demo"/>
        <user name="developer" password="demo"/>
        <user name="support" password="demo"/>
        <user name="infrastructure" password="demo"/>
        <user name="admin" password="admin"/>
   </basicRegistry>
   

   For more information on how to configure other user registry types, such as LDAP, see the Configuring a user registry for Liberty topic in the WebSphere Application Server product documentation.

6. Start the Liberty Server by running the following command inside your bin folder

   ./server start <serverName>
   

7. Verify the service by invoking health url

   http://localhost:9080/analytics-receiver/rest/data/health
   

For more information on administering WebSphere Application Server Liberty, see the Administering Liberty from the command line topic in the WebSphere Application Server product documentation.

1. Change the JAVA_HOME for Analytics:  On the analytics server instance, go to the server.env file 

   Set the java home to java 8 by adding below line in it-  JAVA_HOME= <path to the jdk 8 folder> (path to directory above the bin) 

Installing Persistent Mobile Foundation Analytics Receiver on Tomcat

Ensure that you already have the Persistent Mobile Foundation Analytics Receiver WAR files. For more information on the installation artifacts, see Installing PMF to an application server. The analytics-receiver.war file is found in the <pmf_install_dir>\Analyticsreceiver folder. For more information on how to download and install Tomcat, see Apache Tomcat. Ensure that you download the version that supports Java 8. For more information about which version of Tomcat supports Java 8, see Apache Tomcat Versions.

1. Add analytics-receiver.war file to the Tomcat webapps folder.

2. Uncomment the following section in the conf/server.xml file, which is commented out, in a newly downloaded Tomcat archive.

   <Valve className ="org.apache.catalina.authenticator.SingleSignOn"/>
   

3. Declare the two war files in the conf/server.xml file, and define a user registry.

   <Context docBase ="analytics-receiver-service" path ="/analytics-receiver"></Context>
   <Realm className ="org.apache.catalina.realm.MemoryRealm"/>
   

   The MemoryRealm recognizes the users that are defined in the conf/tomcat-users.xml file. For information on other available options, see Apache Tomcat Realm Configuration HOW-TO.

4. Add the following sections to the conf/tomcat-users.xml file to configure a MemoryRealm.

   • Add the security roles.

     <role rolename="analytics_administrator"/>
     <role rolename="analytics_infrastructure"/>
     <role rolename="analytics_support"/>
     <role rolename="analytics_developer"/>
     <role rolename="analytics_business"/>
     

   • Add a few users with the roles you want.

     <user name="admin" password="admin" roles="analytics_administrator"/>
     <user name="support" password="demo" roles="analytics_support"/>
     <user name="business" password="demo" roles="analytics_business"/>
     <user name="developer" password="demo" roles="analytics_developer"/>
     <user name="infrastructure" password="demo" roles="analytics_infrastructure"/>
     

   • Start your Tomcat Server and verify the service by invoking the health url.

     http://localhost:8080/analytics-receiver/rest/data/health
     

   For more information about how to start the Tomcat Server, see the official Tomcat site. For example, Apache Tomcat 9, for Tomcat 9.0.

Installing Persistent Mobile Foundation Analytics Receiver with Ant tasks

Ensure that you have the necessary WAR and configuration files: analytics-receiver.war. For more information on the installation artifacts, see Installing PMF to an application server. The analytics-receiver.war file is found in the MobileFoundationServer\AnalyticsReceiver.

You must run the Ant task on the computer where the application server is installed. If you want to start the Ant task from a computer on which PMF is not installed, you must copy the file \<pmf_install_dir\>/MobileFoundationServer/mfp-ant-deployer.jar to that computer.

Note: The pmf_install_dir is the directory where you installed PMF.

1. Edit the Ant script that you will use later to deploy Persistent Mobile Foundation Analytics Receiver WAR files.
   • Review the sample configuration files in Sample configuration files for Persistent Mobile Foundation Analytics Receiver.
   • Replace the placeholder values with the properties at the beginning of the file.

   Note: The following special characters must be escaped when they are used in the values of the Ant XML scripts:

   • The dollar sign ($) must be written as $$, unless you explicitly want to reference an Ant variable through the syntax ${variable}, as described in the Properties section of the Apache Ant Manual.
   • The ampersand character (&) must be written as &, unless you explicitly want to reference an XML entity.
   • Double quotation marks (“) must be written as ", except when it is inside a string that is enclosed in single quotation marks.

2. To deploy the WAR file, run the following command:

   ant -f configure-appServer-analytics-receiver.xml install
   

3. Save the Ant file. You might need it later to apply a fix pack or perform an upgrade. If you do not want to save the passwords, you can replace them by ************ (12 asterisks) for interactive prompting.

Prerequisites to Run the Analytics

1. Create the config.properties file at your preferred location and add the following variables: 

   • allowed.hostname =
   • maximum.request = 20 
   • time.window = 1 

   Description of Properties

   • allowed.hostname: 
     This property indicates a single or list of whitelisted servers that are granted permission to send requests to the application.
     If multiple servers need to be whitelisted, each server name should be separated by a comma. 
     Example: 

      allowed.hostname=localhost,127.0.0.1 
     

     The above configuration would allow analytics to work only on localhost or the IP mentioned. All other requests would be rejected. 
     If no value is provided, the default server name for whitelisting is localhost. 

   • maximum.request and time.window:
     These properties indicate the maximum number of invalid login attempts allowed within a configured time interval (defined by time.window). 
     For example, if maximum.request is set to 20 and time.window is set to 1, then 19 invalid login attempts are allowed within 1 minute.
     Once the threshold is reached, unless the configured time.window lapses, the user will not be allowed to log in, even with correct credentials. 

2. Create the environment variable CONFIGURATION_FILE_PATH and provide the full file path of config.properties as its value.

   Example: 

   export CONFIGURATION_FILE_PATH=/opt/config.properties 
   

   You can set this path as desired; there is no mandate to keep the config.properties file under /opt.  Make sure this variable is available on the system as an environment variable; otherwise, Analytics will not be able to identify user configurations and will continue to run on default settings. 

3. Restart the server instance whenever you make any changes to the config.properties file to apply the updates.