Installing Elasticsearch, jCustomer, and jExperience

The jCustomer official and nightly builds are distributed as packages (ZIP or TAR/GZ), which contain the Apache Karaf server with all the jCustomer services bundled and pre-configured. A second distributable is the jExperience Package itself (JAR file), which includes modules to be deployed on the Jahia instance. The next sections describe the installation of both parts.

Installing Elasticsearch server

jCustomer requires Elasticsearch. When you use jExperience and jCustomer together, you must install a standalone version of Elasticsearch.

To install a standalone Elasticsearch:

Download an Elasticsearch 5.x version (5.6.3 or a more recent 5.6.x version, but not 5.7.x) from the following site: https://www.elastic.co/downloads/past-releases/elasticsearch-5-6-3
Uncompress the downloaded package into a directory which the documentation refers to as <elasticsearch-install-dir>.
In the <elasticsearch-install-dir>/config/elasticsearch.yml file replace the cluster.name parameter with your own cluster name.
```
# ---------------------------------- Cluster -----------------------------------
#
# Use a descriptive name for your cluster:
#
cluster.name: YourOwnClusterName
#
```
Record the cluster name and configure your jCustomer instance to point on it later.
Launch the server using bin/elasticsearch on Mac or Linux and bin\elasticsearch.bat on Windows.
Check that the Elasticsearch is up and running by accessing the following URL:
http://<your-server-hostname>:9300

Starting and stopping Elasticsearch

Navigate to the <elasticsearch-install-dir>/bin directory and launch Elasticsearch using the following command:

./elasticsearch

You can then stop the server simply by issuing a CTRL+C inside the console where you launch the Elasticsearch server. Leave it running for now as you will need it running before starting jCustomer.

If you want to install Elasticsearch as a background service on a specific operating system, you may use other packages. You can find documentation on how to do this here: https://www.elastic.co/guide/en/elasticsearch/reference/current/install-elasticsearch.html

Installing jCustomer

Compatibility

Depending on the jExperience version that you deploy on your Jahia Instance, you must get the compatible corresponding jCustomer version. You can find the correct version on the jExperience download page.

Note: Do not download jCustomer directly from the public Apache Unomi website as public versions are not supported. jExperience will not work if it used with a non-compatible version of jCustomer.

Installing jCustomer

As a reminder, you can find the Jahia supported version of jCustomer in the Customer Center. The jCustomer install consists of one unique step, which requires uncompressing the content of the context-server-package-X.X.X.tar.gz (Linux, Solaris, or Mac OSX) or context-server-package-X.X.X.zip into your target installation folder. This creates the context-server-package-X.X.X folder, which is referenced later in this document as <cxs-install-dir>.

Whether you’re installing jCustomer and Elasticsearch locally, remotely, or in a cluster you must to specify an Elasticsearch cluster name. It is recommended to do this before you start the server for the first time. Otherwise you will lose all the data you have stored previously. You can also change the host and port if they need to be modified from the default values.

Attention: If you are installing multiple jCustomer clusters (for example pre-production and production) in the same network, you must ensure that the cluster name is different between the environments. Otherwise you will connect all the nodes together.

To change these settings, you must create or modify for each cluster node a file called <cxs-install-dir>/etc/unomi.custom.system.properties with the following contents:

org.apache.unomi.elasticsearch.cluster.name=YourOwnClusterName
# The elasticSearchAddresses may be a comma separated list of host names and ports such as
# hostA:9300,hostB:9300
# Note: the port number must be repeated for each host
org.apache.unomi.elasticsearch.addresses=localhost:9300

Note: The elasticsearch.yml file is space sensitive and one space at the wrong place will break the file.

Directory layout

The directory layout of an installed jCustomer (after first startup) is as follows:

/bin
Control scripts to start, stop, login, and more
/data
Working directory
- /cache
  OSGi framework bundle cache
- /generated-bundles
  Temporary folder used by the deployers
- /log
  Log files
/deploy
Hot deploy directory
/etc
Configuration files
/instances
Directory containing instances
/lib
Contains the bootstrap libraries
- /ext
  Directory for JRE extensions
- /endorsed
  Directory for endorsed libraries
/system
OSGi bundles repository laid out as a Maven 2 repository. The data folder contains all the working and temporary files for jCustomer. If you want to restart from a clean state, you can wipe out this directory, which has the same effect as using the clean option (see the next section). You must also clear the <elasticsearch-install-dir>/data directory if you want to purge the stored data.

Starting and stopping jCustomer

The first time you start jCustomer is unique. By default the Apache Karaf (OSGi) server will start, but jCustomer's packages will not start automatically. Previous versions started automatically, but Jahia has since then introduced a new migration tool. To start jCustomer, you must first start the Apache Karaf server in any mode (see below), and then start the packages using a shell command.

jCustomer supports the following start modes:

Regular mode
Starts Apache Karaf in foreground including the shell console.
Server mode
Starts Apache Karaf in foreground, without the shell console.
Background mode
Starts Apache Karaf in background. You can also manage Apache Karaf as a system service (see the Integration in the operating system: the Service Wrapper section of the Apache Karaf documentation located here: https://karaf.apache.org/manual/latest/#_service_wrapper). Various run modes are described in details on the "Start, stop, restart, connect" page (https://karaf.apache.org/manual/latest/#_start_stop_restart_connect) of the Apache Karaf documentation. For development, demo and quick test purposes the regular mode is appropriate. The background mode is best suited for a production environment.

Regular mode

For Linux, Solaris, or Mac OSX:

./bin/karaf

For Windows:

bin\karaf.bat

This starts Apache Karaf as a foreground process and displays the shell console. Note that closing the console or shell window will cause jCustomer and Apache Karaf to terminate. In regular mode, you can type 'system:shutdown' or 'logout' in the console to shutdown Apache Karaf.

Starting an Apache Karaf server in a background mode

For Linux, Solaris, or Mac OSX:

./bin/start

For Windows:

bin\start.bat

You can connect to the shell console using SSH or client (see the next section).

Connecting using a client

Even if you start Apache Karaf without the console (using server or background modes), you can connect to the console. This connection can be local or remote. It means that you can access the jCustomer console remotely. To connect to the console, you can use the bin/client Unix script (bin\client.bat on Windows). To connect to a local process you should use Linux, Solaris, or Mac OSX:

./bin/client –h localhost –u karaf

For Windows:

bin\client.bat –h localhost –u karaf

First-time jCustomer start

The first time you start Apache Karaf, the jCustomer packages will not automatically start. You must start the packages using the following Apache Karaf shell command:

unomi:start

This step is only required once, the next time Apache Karaf starts it will automatically start the jCustomer packages.

Note that you can start jCustomer without this command. To do so you will need to modify the setenv.sh file and add the following line:

export KARAF_OPTS="-Dunomi.autoStart=true"

Stopping jCustomer

When you start jCustomer in regular mode, the logout command or CTRL-D key binding helps you logout from the console and shutdown the jCustomer instance. When you start jCustomer in background mode, you can use the bin/stop Unix script (bin\stop.bat on Windows). More generally, you can use the shutdown command (on the CXS console) that works in any case.

karaf@root()> shutdown -h
Confirm: halt instance root (yes/no):

The shutdown command asks for a confirmation. If you want to bypass the confirmation step, you can use the -f (--force) option:

karaf@root()> shutdown -f

You can also use directly halt which is an alias to shutdown -f -h.

jCustomer key and event security

jCustomer uses a mechanism to prevent unauthorized servers and clients to send some specific events. Events such as logins, or properties updates should only be allowed from whitelisted servers. To do that jCustomer uses a combination of a unique key and an IP address to check if a server may send restricted events to jCustomer. This is configured in the etc/org.apache.unomi.thirdparty.cfg file that is created after the initial start of jCustomer. jCustomer must be restarted for the settings from this file to take effect.

Edit the etc/unomi.custom.system.properties file to add a jCustomer key. This key may be any unique string (there is a default one, but it should only be used for testing, never for production). We recommend using something obscure such as a UUID (generate one here) or a SHA checksum (generate one here).

You will also need to configure the IP addresses that will be allowed to send some secure events. Warning: If these requests will go through proxies, you must use the IP address of the last proxy in the chain. For example if your deployment is setup this way: Jahia>Public jCustomer IP>Apache HTTP server>jCustomer, the IP address must be the last IP that is used to connect to jCustomer, in this case the IP address of the HTTP server. Here we call the various IP addresses of the Jahia nodes Jahia_NODE_1, Jahia_NODE_2. Of course if you have more than two nodes you will also need to add them here.

org.apache.unomi.thirdparty.provider1.key=<generated-unomi-key>
org.apache.unomi.thirdparty.provider1.ipAddresses=127.0.0.1,::1,DX_NODE_1,DX_NODE_2
org.apache.unomi.thirdparty.provider1.allowedEvents=login,updateProperties

The jCustomer key will then be required in the jExperience connection setup. Note that the allowedEvents must contain the updateProperties event, as it is now required by jExperience to perform any updates on profile or persona properties. Make sure this value is present especially if you are migrating from previous versions of jCustomer.

Installing the jExperience Package

Deploy modules

The jExperience Package is delivered as a JAR named EnterpriseDistribution-jExperience-version-number.jar, where version-number is the version you are installing, for example 1.11.1. The JAR must be deployed on your Jahia server. While your Jahia server is running, in the Server Administration UI>System components>Modules, click the Upload action and choose the EnterpriseDistribution-jExperience-version-number.jar file to install the package.

Configuring jExperience connection to jCustomer

jExperience’s configuration for the connection to the jCustomer server is setup using OSGi configuration files. These files are located in the /digital-factory-data/karaf/etc directory as is the case for other OSGi configuration files. We also provide a sample configuration file.

Configuration files can be created and edited while Jahia is running. They will be automatically refreshed at a regular interval.

Note: Before Marketing Factory version 1.10.1, you could create and edit configurations using Marketing Factory’s administration UI. Now the configuration in the administration UI is read-only and only editable through configuration files. The jExperience administration UI displays cluster information and connection status.

File location and naming convention

Multiple configuration instances may be deployed by following naming convention:

/digital-factory-data/karaf/etc/org.jahia.modules.jexperience.settings-[CONFIG_NAME].cfg

where [CONFIG_NAME] can be anything you want to identify your configuration

Global or per site configuration

You can use a global jExperience configuration for all the sites or keep configuration per sites. To have the configuration apply only to a given site the following property must be set:

jexperience.siteKey=mySite

Using the siteKey could be useful to override a global configuration to customize it for a given site. If no siteKey provided, the configuration will be considered global.

Note: Multiple global configurations and multiple instance of configurations for the same site could results in randomly chosen configurations.

jExperience with a Jahia cluster

In case of a Jahia cluster installation, the configuration is different depending on the version of Jahia. If you're using the latest version of Jahia 7.3 you can skip the following steps.

Steps only for DX 7.2 and Jahia 7.3 up to 7.3.1.1:

jExperience needs to be configured on each Jahia node, because Jahia is not able to replicate OSGi configurations across the cluster. You will have to replicate manually the configuration files on each Jahia node.
jExperience requires a modification to the Jahia configuration to be able to use correctly the new OSGi configuration. For all the Jahia cluster nodes you will need to edit the file:
```
/digital-factory-data/karaf/etc/org.apache.karaf.cellar.groups.cfg
```

Add this value:

org.jahia.modules.marketingfactory.settings*

To properties:

default.config.blacklist.inbound
default.config.blacklist.outbound

Properties to configure in the jExperience settings file

Site key
As mentioned before, remove this property if the connection should apply to all sites. If you want to use a specific connection for a site, enter the site key.
- Is mandatory: Optional
- Example: jexperience.siteKey=digitall
Apache jCustomer URL
This should be the base administration URL of jCustomer. This address must use https protocol. See section 4 for more information about jCustomer addresses configuration.
- Is mandatory: Yes
- Example: jexperience.jCustomerURL=https://localhost:9443
Apache jCustomer karaf password
The default password for the "karaf" user is "karaf". Please ensure that you never use the default password if the environment you're configuring contains production data.
- Is mandatory: Yes
- Example: jexperience.jCustomerPassword=s9fgjén8TT6qfçè§è89
jCustomer User Name
jCustomer requires a login to access the administration REST API. By default it is accessible with the "karaf" user.
- Is mandatory: Yes
- Example: jexperience.jCustomerUsername=karaf
Trust all certificates
Activate this checkbox if you are using SSL connection and if you are using self-signed (provided by default) or certificates that are not by a trusted certificate authority (not recommended). This is useful for test installations but should not be used for production installations. For your tests though you must know that the jCustomer package is configured with a default SSL certificate.
- Is mandatory: No
- Example: jexperience.jCustomerTrustAllCertificates=false
Use public addresses for admin
- Example: jexperience.jCustomerUsePublicAddressesForAdmin=false
Apache jCustomer key
The jCustomer key is required and should be set to the same value as configured in jCustomer.
- Is mandatory: Yes
- Example: jexperience.jCustomerKey=670c26d1cc413346c3b2fd9ce65dab41
jExperience Google API Key
This key is used by the preview feature and by the geolocation by point feature. The rest of jExperience can work without this key to be filled. Please refer to Google documentation for more information: https://developers.google.com/maps/documentation/javascript/get-api-key
- Parameter key: jexperience.googleAPIKey
- Is mandatory: no (but it is required for personalization based on geolocation point to work)
Timeout in milliseconds
This value defines the default Javascript timeout for request going from the jExperience modules to jCustomer. If jCustomer doesn’t answer to requests fast enough, and the timeout value is reached, the modules will fallback to default variants and behave "cleanly" under the circumstances. This helps protect the system against network issues or potential jCustomer slowdowns or failures. The value of the timeout is a balance to find between your organization expectations on the response time of the content and the infrastructure. The default value is 1500ms which is adapted to local environments where jCustomer typically respond in this delay. For production installations, we recommend to set this value so that it doesn't downgrade the customer experience while still being reasonable in your environment. Our tests show that 300ms is a good balance.
- Example: jexperience.timeoutInMilliseconds=1500
Apache jCustomer cookie name
This value defines the name of the cookie used by jCustomer. By default, use "context-profile-id" . If you changed the value of the property "contextserver.profileIdCookieName" in jCustomer configuration file etc/org.apache.unomi.web.cfg , the values should be the same; otherwise there is no reason to change it.
- Example=: jexperience.jCustomerCookieName=context-profile-id
Apache jCustomer cookie domain
Use the same value as the "contextserver.domain" defined in jCustomer configuration in etc/org.apache.unomi.web.cfg
- Example: jexperience.jCustomerCookieDomain=localhost
Apache Unomi cookie max age in seconds
- Example: jexperience.jCustomerCookieMaxAgeInSeconds=31536000
Ip forwarding header name
- Example: jexperience.ipForwardingHeaderName=X-Forwarded-For
Http Connection pool maximum
- Example: jexperience.httpConnectionPoolMax=200

Roles and permissions

Please refer to the user guide to understand the permissions included with jExperience.