PMF Analytics Receiver Server Installation Guide

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

• System requirements
• Capacity considerations
• Installing PMF Analytics Receiver on WebSphere Application Server Liberty
• Installing PMF Analytics Receiver on Tomcat
• Installing PMF Analytics Receiver with Ant tasks
• Prerequisites to run the Analytics

System requirements

For complete set of system requirements please refer System requirements.

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.

PMF 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 PMF Analytics Receiver on WebSphere Application Server Liberty

Ensure that you already have the PMF Analytics Receiver WAR file. The analytics-receiver.war file is found in the <pmf_install_dir>\Analyticsreceiver folder.

For more information on the installation artifacts, see Installing PMF to an application server.

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.

8. 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 the following line.

     JAVA_HOME= <path to the jdk 8 folder> (path to directory above the bin) 

Installing PMF Analytics Receiver on Tomcat

Ensure that you already have the PMF Analytics Receiver WAR files. The analytics-receiver.war file is found in the <pmf_install_dir>\Analyticsreceiver folder.

For more information on the installation artifacts, see Installing PMF to an application server.

Ensure that you download Apache Tomcat version that supports Java 8.

For more information on how to download and install Tomcat, see Apache Tomcat. 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 PMF Analytics Receiver with Ant tasks

Ensure that you have the necessary WAR and configuration files: analytics-receiver.war. The analytics-receiver.war file is found in the MobileFoundationServer\AnalyticsReceiver.

For more information on the installation artifacts, see Installing PMF to an application server.

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 PMF Analytics ReceiverWAR 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

For more information, see Prerequisites section - Installing and Configuring the Persistent Mobile Foundation Analytics Server.