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
- In the
<elasticsearch-install-dir>/config/elasticsearch.ymlfile 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/elasticsearchon Mac or Linux and
- Check that the Elasticsearch is up and running by accessing the following URL:
Starting and stopping Elasticsearch
Navigate to the
<elasticsearch-install-dir>/bin directory and launch Elasticsearch using the following command:
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
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.
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
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
<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
The directory layout of an installed jCustomer (after first startup) is as follows:
Control scripts to start, stop, login, and more
OSGi framework bundle cache
Temporary folder used by the deployers
Hot deploy directory
Directory containing instances
Contains the bootstrap libraries
Directory for JRE extensions
Directory for endorsed libraries
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>/datadirectory 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/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.
For Linux, Solaris, or Mac OSX:
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:
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
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:
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:
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.
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
The jExperience Package is delivered as a JAR named EnterpriseDistribution-jExperience-1.10.3.jar, which 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-1.10.3.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:
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:
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.
jExperience with a Jahia cluster
In case of a Jahia cluster installation, 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:
Add this value:
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: mf.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: mf.unomiURL=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: mf.unomiPassword=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: mf.unomiUsername=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: mf.unomiTrustAllCertificates=false
- Use public addresses for admin
- Example: mf.unomiUsePublicAddressesForAdmin=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: mf.unomiKey=670c26d1cc413346c3b2fd9ce65dab41
- jExperience Google API Key
- Parameter key: mf.googleAPIKey
- Is mandatory: no (but it is required for personalization based on geolocation point to work)
- Timeout in milliseconds
- Example: mf.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=: mf.unomiCookieName: 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: mf.unomiCookieDomain=localhost
- Apache Unomi cookie max age in seconds
- Example: mf.unomiCookieMaxAgeInSeconds=31536000
- Ip forwarding header name
- Example: mf.ipForwardingHeaderName=X-Forwarded-For
- Http Connection pool maximum
- Example: mf.httpConnectionPoolMax=200
Roles and permissions
Please refer to the user guide to understand the permissions included with jExperience.