Written by The Jahia Team
 
Developers
Sysadmins
   Estimated reading time:
Note: Marketing Factory is renamed to jExperience in version 1.11 and Apache Unomi is renamed to jCustomer. The 1.10 documentation has been updated to reflect the product name change.

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 following address: https://store.jahia.com/contents/modules-repository/packages/MarketingFactory.html  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 jCustomer

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. Rename the file name to org.jahia.modules.marketingfactory.settings-global.cfg (replace "-sample" by "-global")
  2. Edit the following properties (or copy paste the text below):
    # Mandatory connection properties are:
    mf.unomiURL=https://localhost:9443
    mf.unomiPassword=karaf
    mf.unomiUsername=karaf
    
    # Optional properties and there default value:
    # Trust all certificate
    mf.unomiTrustAllCertificates=true
    
    # Use public addresses for admin
    mf.unomiUsePublicAddressesForAdmin=false
    
    # Unomi KEY
    mf.unomiKey=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.