Installation Overview

With SaaS EUEM, AppDynamics hosts the EUEM Processor, Controller, and other backend services for you. Setting up EUEM in this case only requires ensuring that the Web and Mobile EUEM agents are correctly deployed and configured. Alternatively, you can install and run the EUM services and Controller yourself, as described here. An on-premise deployment allows you to store and maintain the data generated by EUEM entirely within your own data center.

The EUEM Processor receives data from the EUEM agents, processes it, stores it, and makes it available to the AppDynamics Controller. If you already have an on-prem AppDynamics Controller, you need to make sure you have upgraded to a compatible version and apply a few configuration changes to the Controller to enable it to work with the on-premise EUEM Processor.

The EUEM installer installs the EUEM Processor and configures the Controller to work with EUEM. To install the Controller, see Install the Controller.

Demo Mode Versus Production Mode

The EUEM installer operates in one of two modes: demo mode or production mode. Demo mode is intended for very small-scale demonstration or evaluation environments. In demo mode, the installer configures the Controller for EUEM support and installs the EUEM Processor on the same machine.

In production mode, the Controller and EUEM Processor are expected to reside on separate, dedicated machines. To deploy EUEM in a production environment you therefor need to run the installer on two machines: first on the Controller machine, to make the necessary updates on the Controller instance, and then again on the EUEM Processor host, to install and configure the Processor.

Specifically, the tasks and the order in which they should be performed are:

For a production environment on-premise EUEM:
1. Run the installer on the Controller host.
2. Run the installer on the EUEM server host.
For a small-scale demonstration environment, simply run the installer once on the Controller host.

In a production environment, the EUEM Processor is intended to operate behind a reverse proxy. There are several reasons for this. A reverse proxy relieves the performance burden of SSL termination from the EUEM processor machine. It also helps ease certificate management and security administration in general. Further, as the connection point for agent beacons, the processor needs to have the security layer of a proxy between itself and the external Internet.

In demo mode, prior to 3.9.4, the EUEM processor listens for connections on port 80 or 443. If you are using these ports starting the Processor requires root permissions. As of 3.9.4, these ports are configurable on installation, so that you should select ports that do not require root privileges to open, for example, 7001 and 7002. The secure port uses a built-in, self-signed certificate.

Controller Configuration

On-premise EUEM requires Controller version 3.8.2 or later. If installing EUEM with an existing on-premise Controller, whether in a production or test environment, be sure to back up the Controller before starting.

The installer makes these changes to the Controller:

Creates an EUEM database schema in the MySQL database shared with the Controller
Registers the EUEM Processor instance with the Controller
Provisions the EUEM-enabled license in the Controller

The Controller will need to be restarted at the end of the configuration changes applied by the installer. If necessary, perform the Controller configuration procedure with the installer at a time when restarting the Controller has minimum impact on service availability.

System Requirements for the EUEM Processor

The requirements and guidelines for the EUEM Processor machine (basic EUEM usage) are:

40 GB extra disk space
64-bit Windows or Linux operating system
Processing: 4 cores
10 Mbps network bandwidth
Minimum 8GB memory total (4GB is defined as max heap in JVM)
NTP enabled on both the EUEM Processor host and the Controller machine. The machine clocks need to be able to synchronize.

A machine with these specs can be expected to handle around 10K page requests a minute or 10K simultaneous mobile users. Adding on-premise Analytics capability requires increasing these requirements - particularly disk space - considerably, depending on the use case.

Running the Installer

The following instructions describe how to run the installer in GUI mode on Linux systems. GUI mode provides a wizard-based approach to installation. Alternatively, you can use a response file for unattended installation or console mode. While the steps and screenshots demonstrate the installation on Linux, the steps to perform a Windows installation are equivalent. The instructions note where there are differences based on the operating systems.

The EUEM Processor must be installed using the same user account on the target machine as the one used to install the Controller, or using an account that has read, write, and execute permissions to the Controller home directory. Installing with incompatible permission levels—for example, attempting to install EUEM as a regular user while the Controller was installed by root user—can result in installation or operational errors.

To start the installer in console mode, start the installer with the -c. For a response file, use the -q switch and specify the response file to use. For example:

 -q -varfile /home/user/response.varfile

See Using the Silent Installer for a sample response file.

Installing On-Premise EUEM in Demo Mode

If you do not already have an existing on-prem Controller, install it as described in Install the Controller. See Controller Configuration for more information.

Get the EUEM Processor installer from the AppDynamics Download Center. Before starting, download the installer distribution and extract it on the target machine.

Install the on-premise EUEM in Demo mode as follows:

At the command line, navigate to the directory where you extracted the installer archive and start the installer as follows:
- On Linux, run the following command:
```
./euem-installer-64bit-linux.sh
```
- On Windows, run the following command:
```
euem-installer-64bit-windows.bat
```
In the Welcome screen, click Next.
The License Agreement page appears.
Scroll to the end of the license agreement, click Accept, and click Next.
Select the directory in which you want to install the EUEM Processor and click Next.
Choose Demo for the installation mode and click Next. In this mode, the installer looks for a Controller on the current machine and applies changes to it. It then installs the EUEM Processor on the same machine.
Enter the hostname for the EUEM processor and verify or edit the default listening ports. The hostname and ports shown here are where the EUEM Agents send their beacons. Use the hostname for the machine as addressed on the network rather than "localhost" to ensure that the EUEM Processor can be registered correctly in the Controller configuration.
Enter the Controller home directory and click Next. You can specify the directory by clicking Browse and selecting it in the Select Directory dialog box.
In the AppDynamics Controller Database Information fields, enter the connection settings used by the Controller to access its MySQL database, along with settings for a new user account in the database to be used by the EUEM Processor.

Using localhost to indicate the database host will help you avoid permissions issues.
The installer connects to the Controller database and adds a new table for on-premise EUEM, eum_db.
In the EUEM Database Password field, enter a password for a new database user for EUEM, eum_user. Confirm the password and click Next
The installer performs the installation based on your settings.
When the installer is finished, note the information in the Complete page. It contains next steps and information on how to start the EUEM Processor. Click Finish to close the installer.
Restart the Controller to complete the installation.

The address that the agents use to send their beacons to the EUEM Processor needs to be updated. For Web EUEM, the Controller updates the JavaScript agent. Simply re-download and deploy it, as described in Set Up and Configure Web EUM. For Mobile EUEM, the mobile applications themselves need to updated, using the mobile SDKs. For more information, see Customize Your Android Mobile Instrumentation and Customize Your iOS Mobile Instrumentation.

Installing On-Premise EUEM in Production Mode

Installing on-premise EUEM for a production environment requires running the EUEM installer on two machines:

On the Controller host
On the EUEM Processor host

The order in which you perform the tasks is important. The EUEM installer must be run on the Controller host before you run the installer on the EUEM Processor host.

Before starting, verify the Controller installation and version and back up the Controller.

Get the EUEM Processor installer from the AppDynamics Download Center. Before starting, download the installer distribution and extract it on the target machine and on the Controller machine.

Configuring the Controller for a production EUEM deployment

Configure the Controller for an on-premise EUEM deployment in production mode as follows:

At the command line, navigate to the directory where you extracted the installer archive and start the installer as follows:
- On Linux, run the following command:
```
./euem-installer-64bit-linux.sh
```
- On Windows, run the following command:
```
euem-installer-64bit-windows.bat
```
In the Welcome screen, click Next.
The License Agreement page appears.
Scroll to the end of the license agreement, click Accept, and click Next.
Select the directory in which you want to install the EUEM Processor and click Next.
Choose Production Controller Configuration for the installation mode and click Next. In this mode, the installer looks for a Controller on the current machine and configures it to work with on-premise EUEM.
Enter the hostname for the EUEM Processor along with the HTTP or HTTPS listening ports. These values should be the hostname and port that the Controller uses to connect to the EUEM Processor on the network.
Enter the Controller home directory and click Next. You can specify the directory by clicking Browse and selecting it in the Select Directory dialog box.
In the AppDynamics Controller Database Information fields, enter the connection settings used by the Controller to access its MySQL database, along with settings for a new user account in the database to be used by the EUEM Processor.

Using localhost to indicate the database host will help you avoid permissions issues.
The installer connects to the Controller database and adds a new table for on-premise EUEM, eum_db.
In the EUEM Database Password field, enter a password for a new database user for EUEM, eum_user. Confirm the password and click Next
The installer performs the installation based on your settings.
When the installer is finished, note the information in the Complete page. It contains any next steps. Click Finish to close the installer.
Restart the Controller to complete the installation.

Now run the installer on the EUEM Processor target machine, as described next.

Installing the EUEM Processor for a production deployment

After setting up the Controller on the Controller host, run the on-premise EUEM installer on the machine on which you want to install the EUEM Processor.

At the command line, navigate to the directory where you extracted the installer archive and start the installer as follows:
- On Linux, run the following command:
```
./euem-installer-64bit-linux.sh
```
- On Windows, run the following command:
```
euem-installer-64bit-windows.bat 
```
In the Welcome screen, click Next.
The License Agreement page appears.
Scroll to the end of the license agreement, click Accept, and click Next.
Select the directory in which you want to install the EUEM Processor and click Next.
Choose Production EUEM Processor Installation for the installation mode and click Next. In this mode, the installer installs and configures the EUEM Processor on the current machine.
Enter the hostname or IP address of the Controller and the HTTP or HTTPS listening port for the EUEM Processor.

The default EUEM HTTP port is 7001 and HTTPS is 7002. These are the ports to which the agents connect to send EUEM data. For secure connections from agents, you should terminate SSL at a reverse proxy that sits in front of the EUEM Processor in the network path and forward connections to this port.
Using a reverse proxy is the best practices method of setting up HTTPS connections for an on-prem EUEM Processor. If this is not possible in your installation, however, it is possible to to set HTTPS support manually. See Customizing HTTPS Support Manually.
In the database connection settings, enter the connection information the EUEM Processor will use to connect to the Controller database. Also enter the password you specified for the EUEM user when configuring the Controller in the previous section.

With the initial configuration information gathered, the installer now completes the setup of the EUEM Processor.

The processor does not start automatically at the completion of installation. To start it, use the commands described in Starting and Stopping the EUEM Processor.

The address that the agents use to send their beacons to the EUEM Processor needs to be updated. For Web EUEM, the Controller updates the JavaScript agent. Simply re-download and deploy it, as described in Set Up and Configure Web EUM. For Mobile EUEM, the mobile applications themselves need to updated, using the mobile SDKs. For more information, see Customize Your Android Mobile Instrumentation and Customize Your iOS Mobile Instrumentation for more information.

Using a Custom Keystore

New in 3.9.4 The installer opens a secure listening port for the EUEM Processor that uses a default self-signed certificate in a bundled keystore. The keystore file is located at eum-processor/bin/ssugg.keystore. You can replace the default keystore and certificate by generating a new keystore and configuring the processor to use it, as described in the following sections. These instructions describe how to create a new keystore for the processor. You can use an existing keystore instead, but make sure that the keystore matches the requirements outlined below.

The following instructions describe how to create a custom keystore, configure the EUM Processor to use it, and test the results. The commands demonstrate the steps in Linux, but are similar to those used for Windows. Be sure to adjust the paths as appropriate for your system.

The procedure is made up of three parts:

Create a new keystore
Configure the EUEM Processor to use the keystore
Restart and test

Create a New Keystore

At a command prompt, navigate to the eum-processor home directory:
```
cd <euem_home>/eum-processor
```
Create a new keystore with a new unique key pair as follows:
```
../jre/bin/keytool -genkey -keyalg RSA -validity 3560 -alias 'eum-processor' -keystore bin/mycustom.keystore
```
This creates a new public-private key pair and a self-signed certificate and stores it in an alias called "eum-processor". Be sure to use RSA as the key algorithm. The first and last name fields are used as the common name (CN) of the certificate, so you should use your server name.
Configure the keystore as prompted. For the keystore password, use "welcome". Leave the key password (the final prompt) blank. Provide appropriate values for the other fields, such as organization name, location, and so on.
Generate a certificate signing request (CSR):
```
../jre/bin/keytool -certreq -keystore bin/mycustom.keystore -file /tmp/eum.csr -alias 'eum-processor'
```
This generates a certificate signing request based on the contents of the eum-processor alias. The output file, /tmp/eum.csr in the example, should be sent to the Certificate Authority for signing. After you receive the signed certificate, proceed as follows.
Install the certificate for the Certificate Authority used to sign the .csr file:
```
../jre/bin/keytool -import -trustcacerts -alias myorg-rootca -keystore bin/mycustom.keystore -file /path/to/CA-cert.txt
```
This mports your CA's root certificate into the keystore and stores it in an alias called "myorg-rootca"
Install the signed server certificate as follows:
```
../jre/bin/keytool -import -keystore bin/mycustom.keystore -file /path/to/signed-cert.txt -alias eum-processor
```
This imports your signed certificate over the top of the self-signed certificate in the eum-processor alias.

Configure the EUEM Processor to Use the New Keystore

Place the new keystore file under the bin directory of your EUEM Processor home directory.
Open the onprem.properties file in the bin directory for editing.
Add the following properties to the file (if not already present), setting their values to the name of the custom keystore file and password for the certificate, respectively:
- com.appdynamics.eum.server.keystore.filename=mycustom.keystore
- com.appdynamics.eum.server.keystore.password=custom.password

Now restart the processor and test the configuration.

Restart and Test

Restart the EUM Processor. From the EUEM Processor home directory:
```
bin/eum.sh stop
bin/eum.sh start
```
Verify the new SSL server cert works by opening the following page in a browser:
```
https://<eum-processor>:7002/eumcollector/get-version
```
If you get a successful response, the configuration works.

Customizing HTTPS Support Manually

In 3.9.4 and later, the installer configures an HTTPS listening port with a default keystore for the EUEM Processor. In previous versions, to use HTTPS, you must do two things:

Change the EUEM Processor port
Tell the agent where to send the beacons

Change the EUEM Processor port

In the EUEM Processor host, open <EUEM_home>/eum-processor/bin/onprem.properties with a text editor.

Make the following edits and additions to the file:

com.appdynamics.eum.server.port.https=<port-number>  // the port on the EUEM Processor for HTTPS traffic
com.appdynamics.eum.server.httpsProduction=true  // enables HTTPS support for production

Save the file.

Tell the agent where to send the beacons

There are two different ways to accomplish this task.

Modify the controller's domain.xml

This is a global mechanism, but it requires restarting the Controller

1. In the Controller host, open <Controller_home>/appserver/glassfish/domains/domain1/config/domain.xml with a text editor.
2. Add the following property:
```
<jvm-options>-Dappdynamics.controller.eum.beacon.hostNameHttps=<processor host>:<https port></jvm-options>
```
  where <processor host> is the EUEM Processor hostname and <https port> is the HTTPS port you configured in the previous step.
3. Save the file.
4. Restart the Controller.

Use the Controller UI for each application

This method does not require a Controller restart, but must be done for each application

1. In the Controller UI for each application, access the EUEM configuration screen. Click Configure->Instrumentation.
2. Select End User Experience tab.
3. Select Web Page JavaScript Instrumentation sub-tab.
4. Expand Advanced.
5. Expand Customize Your Deployment.
6. Enter the EUEM Processor hostname and port in the EUM Data Collector URL (Optional) field.
7. Click Save.

Using the Silent Installer

Instead of using the installer in GUI mode, you can use the silent installer to perform an unattended installation. The silent installer takes a response file as a source for the initial configuration settings. It's useful for scripting installation or performing large scale deployments.

To use the silent installer

Create a file named response.varfile on the machine on which you will run EUEM installer with the following contents.

#Response file for AppDynamics End User Experience Management 3.9.0.0
# 
sys.adminRights$Boolean=false
euem.httpPort=80
euem.httpsPort=443
euem.Host=<euem_processor_hostname>
mysql.databaseRootUser=root
sys.languageId=en
mysql.databasePort=3388
mysql.dbHostName=localhost
sys.installationDir=/AppDynamics/EUEM
euem.InstallationMode=demo
controller.installationDir=<path_to_controller_home>
controller.Host=localhost
eumDatabasePassword=<eum_user_password>
eumDatabaseReEnterPassword=<eum_user_password>
mysqlRootUserPassword=<root_user_password>

Adjust values of the installation parameters based on your own environment and requirements. In particular, modify the directory paths and passwords to match your environment.
The installation mode in the response.varfile above is set to demo mode. For production mode, run the installation with the response.varfile twice, once on the Controller machine and again on the EUEM Processor host:
1. To set up the Controller, change the mode by changing the euem.InstallationMode value to:
```
euem.InstallationMode=production-controller-setup
```
2. For the EUEM Processor installation, change the mode to:
```
euem.InstallationMode=production-eum-setup
```

Run the installer with the following command:

./euem-installer-64bit-linux.sh -q -varfile response.varfile

On Windows, use:

euem-installer-64bit-windows.bat -q -varfile response.varfile

Starting and Stopping the EUEM Processor

Start the EUEM Processor as follows:

On Linux, from the eum-processor directory, run the following command to start the production EUEM Processor:
```
./bin/eum.sh start
```
If you have not changed the default demo ports from 80 and 443 (available from 3.9.4), you need to run the command as sudo, as follows:
```
sudo ./bin/eum.sh start
```
On Windows, start the EUEM Processor by running:
```
bin\eum-processor.bat start
```

You can check if the EUEM Processor is running and accessible by going to http://<euem-host>:7001/eumaggregator/ping with your browser. Your browser should display ping.

To stop the EUEM Processor:

On Linux, from the eum-processor directory, run:
```
./bin/eum.sh stop
```
On Windows, from the eum-processor directory, run:
```
bin\eum-processor.bat stop
```

Troubleshooting the On-Premise EUEM Installation

The following sections provide troubleshooting information for the EUEM installation.

End user data does not appear in the Controller

If end user data does not appear in the Controller, follow these steps to troubleshoot the installation:

Check the Controller logs for errors in attempting to connect to the EUEM processor. Also, see if the Controller UI allows you to enable EUEM. If so, it's likely that the connection between the Controller and EUEM Processor is working.
Check the logs of the EUEM Processor, especially <EUEM_home>/logs/eum-processor.log. In the log, verify that the processor started successfully and is receiving beacons from agents.
Make sure that the EUEM JavaScript Agent is actually injected into the monitored page and that the agent can load the remote JavaScript.
Use browser debugging tools to check for JavaScript errors in the monitored page.
If you're still not able to identify and correct the issue, contact AppDynamics Support.

License exception on starting the EUEM Processor

If after installation the EUEM Processor fails to start with a EUEM license exception, try installing the license manually.

With the Controller running and accessible to the EUEM Processor machine, install the license manually as follows:

Verify that the JAVA_HOME/bin is in the system PATH variable and points to a Java 1.7 instance.
In Windows, open an elevated command prompt (run as administrator).
From the command line, navigate to the eum-processor directory under your EUEM Processor home.
To give the processor the Controller database password, use a text editor to open the OnPremStore.properties file, found in the bin directory, and replace **CONTROLLER_PASSWORD** with the appropriate password.
From the eum-processor directory, run the following script:

- On Linux:
  ./bin/provision-license
- On Windows:
  bin\provision-license.bat <path to license file>

Modifying Settings

The installer writes most of the configuration settings to the following configuration file:

<EUEM_home>/eum-processor/bin/onprem.properties

After installation is complete, you can edit the file to modify any of the user configurable settings, as described in the comments within the file.

The properties file OnPremStore.properties defines the location of the file store used by EUEM. By default, this storage location is in the EUEM home directory. The data store location can be changed, but it must be a location that is writable by the user starting the EUEM Processor. At startup, the EUEM processor checks that it can write to the file store location

Verify Configuration After Controller Upgrade

Upgrading the Controller configured for on-premise EUEM may overwrite certain Controller configuration customizations originally applied by the EUEM installer. After you upgrade the Controller version, verify and if needed restore EUEM configuration settings manually.

To verify and restore the EUEM settings in the Controller configuration:

From a terminal, navigate to the following directory:
<Controller_home>/appserver/glassfish/domains/domain1/config
Open the domain.xml for editing and the backup of the domain.xml file that was generated during the upgrade process. The backup file is located in the same directory and is named with the following pattern:
domain.xml_yyyyMMdd_HHmmss.bak
Where yyyyMMdd_HHmmss is the time at which the backup was created.

Compare the following JVM options under the java-config element. The domain.xml version should match the one in your backup domain.xml file.

<java-config>
    ...
    <jvm-options>-Dappdynamics.controller.eum.cloud.hostName=http://controller.example.com:80</jvm-options>
    <jvm-options>-Dappdynamics.controller.eum.beacon.hostName=hostname1</jvm-options>
</java-config>

Replace the values of the appdynamics.controller.eum.cloud.hostName and appdynamics.controller.eum.beacon.hostName options in domain.xml with those in the backup file and save the file.
Restart the Controller.

Install the On-Premise End User Experience Management Processor