Written by The Jahia Team
 
Developers
Sysadmins
   Estimated reading time:

This topic show you how to run jExperience as a local instance.

Note: For information on advanced configuration, security recommendations, and clustering, see Installing and configuring jExperience

Installing the JDK

Install JDK 8 (see http://www.oracle.com/technetwork/java/javase/downloads/index.html) and ensure you set the JAVA_HOME variable (https://docs.oracle.com/cd/E19182-01/820-7851/inst_cli_jdk_javahome_t/).

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 5.6.16.
  2. Edit the config/elasticsearch.yml file and change thecluster.name property to <defineYourClusterName>. For example, rename cluster.name to myCluster.
  3. Start Elastic Search: 
    ./bin/elasticsearch

Installing jCustomer

To install jCustomer:

  1. Download and unzip jCustomer.
  2. Add a new text file in the <unomi-install-folder>/etc folder: unomi.custom.system.properties and add the property org.apache.unomi.elasticsearch.cluster.name to <defineYourClusterName> (i.e org.apache.unomi.elasticsearch.cluster.name=myCluster ).
  3. (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.
  4. (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.
  5. Start jCustomer using:
    ./bin/karaf
  6. On the first start, you'll need to execute the following command: 
     unomi:start
    Wait for startup to complete. This step won't be necessary on the next server startups, the jCustomer bundles (packages) will start automatically.
  7. 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.
  8. 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.

Follow the steps below if the server on which your Jahia - Enterprise Distribution ONLY - is running can access the Internet:

  1. Go to the Module Management interface of a running Jahia (Enterprise Distribution) instance.
  2. Click on Available modules and type "jExperience" in the search box.
  3. Select the Enterprise jExperience Package and click Download.

Configuring jExperience connections to customer

Once the jExperience module is started, it requires a configuration file. You can either create a file from scratch or download this sample file

  1. Ensure the file name is org.jahia.modules.jexperience.settings-global.cfg 
  2. 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=false
    
    # Use public addresses for admin
    jexperience.jCustomerUsePublicAddressesForAdmin=false
    
    # Unomi KEY
    jexperience.jCustomerKey=670c26d1cc413346c3b2fd9ce65dab41
    

    The configuration reloads without restarting the Jahia server. 

  3. If you want to use the "personalization using geolocation by point" feature, you'll need add a Google API key to the parameter "mf.googleAPIKey".  If you don't have one, you can request it here: https://developers.google.com/maps/documentation/javascript/get-api-key.
  4. To verify that the connection is working:
    1. Go to Jahia>Edit Mode (on any site where jExperience is enabled)>Site settings>Manage connection to jCustomer. 
    2. Verify that the jCustomer Status: ONLINE.
You can now use jExperience.