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:

1. Download Elasticsearch 7.16.3 from the following site: https://www.elastic.co/downloads/past-releases/elasticsearch-7-16-3
2. Uncompress the downloaded package into a directory which the documentation refers to as <elasticsearch-install-dir>.
3. 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.

4. Launch the server using bin/elasticsearch on Mac or Linux and bin\elasticsearch.bat on Windows.
5. Check that the Elasticsearch is up and running by accessing the following URL:
   http://<your-server-hostname>:9200

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.

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 jcustomer-X.X.X.tar.gz (Linux, Solaris, or Mac OSX) or jcustomer-X.X.X.zip into your target installation folder. This creates the jcustomer-X.X.X folder, which is referenced later in this document as <jcustomer-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.

To change these settings, you must create or modify for each cluster node a file called <jcustomer-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:9200,hostB:9200
# Note: the port number must be repeated for each host
org.apache.unomi.elasticsearch.addresses=localhost:9200

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,JAHIA_NODE_1,JAHIA_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.2. 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.

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. 

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: No
  • Example: jexperience.siteKey=digitall
• 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
• jCustomer karaf 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
• 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=s9fgjen8TT6qfce89
  • Allowed characters:
    • Supported characters: alphanumerical, !()+*-#$@_`.:=/^?~
    • Not supported characters: %;{}&[]<>|\',
• 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
  • Is mandatory: No
  • Example: jexperience.jCustomerUsePublicAddressesForAdmin=false
• 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
  • Is mandatory: No (but it is required for personalization based on geolocation point to work)
  • ​Parameter key: jexperience.googleAPIKey
• 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.
  • Is mandatory: No (default is 1500 milliseconds)
  • Example: jexperience.timeoutInMilliseconds=1500
• jCustomer public URL - Available since jExperience 2.7.2 & 3.x
  This value specifies the jCustomer public URL that will be used by the visitor browser (client side requests) to reach jCustomer public APIs (/context.json, /eventcollector). 
  Using this property makes it really easy to use jExperience as a proxy to jCustomer and therefore ensure that jCustomer server and cookies are seen by the browser as "first party", to avoid any browser restriction on third party domain servers & cookies. By default, if this property is not present, the public address is read from jCustomer config (/cxs/cluster). 
  • This property supports 2 placeholders:
    • $WEBAPP_CONTEXT: will be replaced by the current webapp application context if there is one.
    • $CURRENT_SITE: will be replaced by the rendered page site key.
  • Supported values:
    • $WEBAPP_CONTEXT/modules/jexperience/proxy/$CURRENT_SITE : This will use the internal jExperience proxy, so all the public requests will use jExperience as proxy. Jahia recommends that you use this value. It ensures that calls to context.json / eventCollector are always done on the same domain as your website. 
    • /your_own_local_proxy : In case the jExperience server is already behind a proxy, you could reuse your own proxy then forward to jCustomer
    • http://your-jcustomer-adress : In case you would like to use directly an absolute address of your own, it's still possible.
  • Is mandatory: No
  • Example: 
    • jexperience.jCustomerPublicURL=$WEBAPP_CONTEXT/modules/jexperience/proxy/$CURRENT_SITE
    • In the example above, the URL of the calls to jCustomer context.json and eventCollector will look like this https://mysitedomain.com/modules/jexperience/proxy/mysite/context.json
• 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.
  • Is mandatory: No
  • Example: jexperience.jCustomerCookieName: context-profile-id
• jCustomer cookie domain
  Use the same value as the "contextserver.domain" defined in jCustomer configuration in etc/org.apache.unomi.web.cfg
  • Is mandatory: Yes
  • Example: jexperience.jCustomerCookieDomain=localhost
• jCustomer cookie max age in seconds
  • Is mandatory: No
  • Example: jexperience.jCustomerCookieMaxAgeInSeconds=31536000
• Ip forwarding header name
  • Is mandatory: No
  • Example: jexperience.ipForwardingHeaderName=X-Forwarded-For
• Http Connection pool maximum
  • Is mandatory: No
  • Example: jexperience.httpConnectionPoolMax=200
• Excluded Devices Classes
  This configuration setting makes it possible to ignore events generated by specific types of clients (for example robots, mobile devices, known malicious tools, ...). When such a client (or device class) is detected, their events are ignored and not sent to jCustomer. These classes are defined by the YUAA library using the client's "User-Agent" HTTP header, the list of possible devices can be found here and processed via rules defined here.
  • Is mandatory: No
  • Configuration name: jexperience.excludedDevicesClasses
  • Example: jexperience.excludedDevicesClasses=Robot,Robot Mobile,Robot Imitator,Hacker,Unknown
    In case of a request to Jahia with a user-agent named "bitlybot", a look-up is done in the user agents list, it matches the Robots.yml configuration, device class is Robot. As part of the excludedDevicesClasses config, no request will be sent to jCustomer. 

Roles and permissions

For information about permissions included with jExperience, see About jExperience permissions.