/monitor-analytics web application

This installation step is only necessary if interaction data is to be collected within map.apps on the client side.

To install the webapp of service.monitor deploy the given WAR file from monitor-analytics.war to the Servlet Container that shall be used.

Configuration adjustment

The following configuration files are processed by map.apps:

  • WEB-INF/classes/default-application.properties (DO NOT EDIT)
    This file contains all configuration options of map.apps with their default values.

  • WEB-INF/classes/custom-application.properties
    If a change to the working directory (data.directory.location) or config directory (config.directory.location) is required, the change has to be made in this file. Any further changes have to be made in the following file.

  • [config.directory.location]/application.properties
    Make changes to the configuration by editing this file.
    The default config directory (config.directory.location) of map.apps is ${user.home}/.mapapps. This file is not created automatically, the file WEB-INF/classes/config-template/application.properties can be used as a template. Only keep settings in the file that have been changed or those that refer to values from the secrets.properties, if you do not want to use the secrets.properties file.

  • [config.directory.location]/secrets.properties
    You should store sensitive data such as passwords or API keys in this file and reference them as described in the sample.

The format of the configuration files must correspond to the Java Properties file format .

After making the changes, restart the servlet container or refresh the context.

Environment variables

You can also set the value of all configuration parameters using environment variables. These always override the values you set in the application.properties. This allows to easily customize {product-name} configuration in containerized environments, for example.

You need to translate the names of the configuration properties when using them as environment variables: Only use uppercase letters and replace any dot . by an underscore _.

Example: security.oauth.provider becomes SECURITY_OAUTH_PROVIDER. This pattern applies to all configuration parameters.

Configuration of passwords and secrets

Sensitive data such as passwords or API keys should be stored in the file [config.directory.location]/secrets.properties following the pattern secretKey=value. Unlike previous software versions, default passwords are no longer provided. All required passwords must be set during installation. The password encoding is set to SHA-512 by default and can be adjusted using the security.user.pwenc property. For instance, you can define the password for administration access as follows:

secrets.properties
# Password for administrative access
secret.admin.pw=mySecretValue

You then refer to the entry in the application.properties file:

application.properties
# Reference to entry in secrets.properties
security.user.admin.pw=${secret.admin.pw}

Storing the secrets separately in the secrets.properties file prevents gaining knowledge of configured secrets by retrieving the application’s configuration.

Secure the secrets.properties file by assigning appropriate access authorization and encrypt them using the operating system’s tools, if necessary.

In dynamic deployment scenarios, like the operation in a Docker container, the secrets.properties file can also be generated or managed externally.

Configuration

Elastic Ingest Pipeline

The Usagelog web application uses by default the Elastic Ingest Pipeline to process client-side interaction data from map.apps and forward it to Elasticsearch. The following application.properties configuration sets the properties to elasticsearch:

application.properties
analytics.elastic.url=https://elasticsearch.example.com
analytics.elastic.username=elastic
analytics.elastic.password=${secret.monitoring.elastic.password}

Restrict log endpoint access

It may be desired to restrict access to the /usage/log endpoint for persisting data. This can be done by setting up a list of allowed host names. Those host names will be tested against the HTTP Header value Referer. The referrer value typically contains the url of the web page sending the request.

default-application.properties
analytics.usagelog.referers=*

The default setting allows for sending /usage/log requests from anywhere.

Example

With the following setting, the restrictions below apply.

application.properties
analytics.usagelog.referers=example.com,https://www.example.net

The endpoint allows requests from pages that have, for example, the following HTTP header values:

  • http://example.com/application/index.html

  • https://example.com/webapp/somePage.jsp

  • https://www.example.net/client.aspx

The endpoint would not allow or store requests with such referrer values:

  • http://www.example.net/client.aspx because the setting explicitly points to https protocol.

  • http://www.example.org/some-page.html because the URL is not listed in the property.

Overview of all default values

See \monitor-analytics\WEB-INF\classes\default-application.properties for an overview of the default values of the used properties.

The default value for [data.directory.location] is $\{user.home\}/.monitor.

In case the Tomcat server is operated as a windows service this folder corresponds to the user that executes the Tomcat service. If no such user is configured the Tomcat server runs under the system user’s account (not recommended!). In this case the .monitor folder is to be found under path C:\Windows\System32\config\systemprofile\.monitor.

If a custom folder should be used to store Analytics data, define this path in \monitor-analytics\WEB-INF\classes\custom-application.properties inside the webapp on the Tomcat.
Linux

When installing service.monitor on Linux systems, you have to change the following parameter in configuration file \monitor-analytics\WEB-INF\classes\custom-application.properties:

data.directory.location=$\{user.home\}/.monitor

to e.g.

data.directory.location=/opt/data/.monitor