jExperience quick install

This topic shows you how to run jExperience on a local environment. To run jExperience you:

• Install the Java JDK, Elasticsearch, and jCustomer (the Jahia distribution of Apache Unomi)
• Deploy the jExperience module in Jahia
• Configure the connection between jExperience and jCustomer

Installing the JDK

Install JDK 8 (see Oracle Java SE Downloads) and set the JAVA_HOME variable (see Oracle's Installing the JDK Software and Setting JAVA_HOME documentation). Note that JDK 11 is also supported but JDK 8 is the preferred version for compatibility reasons.

Installing and configuring Elasticsearch

You can find the Elasticsearch prerequisites here: https://www.elastic.co/guide/en/elasticsearch/reference/current/setup.html

To install and configure Elasticsearch:

1. Download and unzip Elasticsearch 7.4.2.
2. Edit the config/elasticsearch.yml file and change thecluster.name property to your own cluster name. It's important to use a dedicated cluster name because Elasticsearch will automatically try to connect with other servers on the same network, leading to conflicts between each local environment. For example, you can change the property value to myclustername.

   cluster.name: myclustername

   Note: The pound sign (#) comments out properties in the file. Remember to remove the pound sign when you specify the cluster name.
3. Start Elasticsearch. 

   ./bin/elasticsearch

Installing jCustomer

Install jCustomer and create a properties file that specifies your Elasticsearch cluster name.

To install jCustomer:

1. Download and uncompress jCustomer 1.5.1 here or login to the Resource Center to access the download.
2. After unzipping, navigate to the jcustomer-1.5.1/etc folder.
3. Create a new .properties file and name it  unomi.custom.system.properties.
4. Add the following entry to the file: org.apache.unomi.elasticsearch.cluster.name=<yourClusterName> where <yourClusterName> is the cluster name that you specified for Elasticsearch earlier. For example:

   org.apache.unomi.elasticsearch.cluster.name=myclustername

5. Save the file.
6. (Optional) jCustomer requires an IP database to resolve IP addresses to the user location. The GeoLite2 database can be downloaded from MaxMind here: http://dev.maxmind.com/geoip/geoip2/geolite2/
   Simply download the GeoLite2-City.mmdb file into the etc directory.
7. (Optional) jCustomer includes a geocoding service based on the Geonames database that is used to create conditions on countries or cities.
   Get the allCountries.zip database from here: allCountries.zip. Download it and put it in the etc directory without unzipping it. The import can take about 15 minutes and runs in the background.
8. Start jCustomer using the following command.

   ./bin/karaf

9. On the first start, you also must execute the following command.

    unomi:start

   Wait for startup to complete. This step is not necessary on future server startups. The jCustomer bundles (packages) will start automatically.
10. Try accessing https://localhost:9443/cxs/cluster with username karaf and password karaf . If you receive a certificate warning in your browser, accept the warning as it is safe.
11. You can try accessing https://localhost:9443/cxs to check the available jCustomer services.

Enabling jExperience modules

If your server does not have access to internet, download the module from the Jahia store  and deploy it to your Jahia server. If the server on which your Jahia Enterprise Distribution is running can access the internet, follow the steps below.

To enable jExperience modules:

1. Open your Jahia Enterprise Distribution instance, and navigate to Administration>System components>Modules.
   
   
2. Click on Available modules and type jExperience in the Search module by keyword field.
3. Select the jExperience module and click Download.
4. Once the download completes, select Installed modules, locate the jExperience module. The status should be Started.
5. Click the module. In Usage in sites, enable the module for each site where you want to use it.

Configuring the jExperience connection to jCustomer

Once the jExperience module is started, it requires a configuration file to connect to jCustomer.

To configure the jExperience connection to jCustomer:

1. In your Jahia installation folder, navigate to the digital-factory-data/karaf/etc subfolder. For example, navigate to:

   Jahia-8.0.0.0/digital-factory-data/karaf/etc

2. Create a new .cfg file named org.jahia.modules.jexperience.settings-global.cfg. Either create a file from scratch or download this sample file. 
3. Edit the following properties (or copy-paste the text below):

   # Mandatory connection properties are:
   jexperience.jCustomerURL=https://localhost:9443
   jexperience.jCustomerPassword=karaf
   jexperience.jCustomerUsername=karaf
   
   # Optional properties and there default value:
   # Trust all certificate
   jexperience.jCustomerTrustAllCertificates=true
   
   # Use public addresses for admin
   jexperience.jCustomerUsePublicAddressesForAdmin=false
   
   # Unomi KEY
   jexperience.jCustomerKey=670c26d1cc413346c3b2fd9ce65dab41
   

   The configuration reloads without restarting the Jahia server. 

4. In the same folder, find and remove any other files starting with org.jahia.modules.jexperience.settings.
5. If you want to use the "personalization using geolocation by point" feature, you must add a Google API key to the parameter "mf.googleAPIKey". If you don't have one, you can request it here: developers.google.com/maps/documentation/javascript/get-api-key.
6. To verify that the connection is working:
   1. Go to Jahia>Edit Mode on any site where jExperience is enabled. Then select Site settings>Manage connection to jCustomer. 
   2. Verify that the jCustomer Status: ONLINE.