Configuration and Fine Tuning

  Written by The Jahia Team
   Estimated reading time:

1 Overview


1.2 What's in this documentation?

This document is intended to give an overview of the various aspects of advanced installation, configuration and the fine-tuning of Marketing Factory v1.5.

It is intended for system administrators and advanced users.

This guide is structured in the following way:

  • Prerequisites: prerequisites and system requirements
  • Installation: Installation of Unomi Server and Marketing Factory as well as the description of how to start and stop the server.
  • Configuring main Context Server features

Should you have questions, please do not hesitate to contact us as mentioned on our website (

2 Prerequisites

2.1 Introduction

The Marketing Factory is composed of two parts:

  1. A dedicated Context Server (aka Apache Unomi Server or CXS), that provides data collection, processing and evaluation.
  2. A set of modules, deployed on a Digital Factory 7.1+ server, which are responsible for submitting data to the Context Server and obtaining evaluated personalized context data back.

This chapter lists requirements for the Context Server itself. Please, refer to the dedicated document (Configuration and fine tuning Guide - Digital Factory for the Digital Factory requirements.

2.2 Minimal System Requirements

Please find below the minimum system requirements in order to properly run Marketing Factory v1.0.


  • Windows
  • Linux
  • Solaris
  • Mac OSX

Suggested Min. Production Environments:

  • Quad Core (64 bit CPU and OS)
  • 4 GB RAM
  • 100 GB HDD

2.3 Java Virtual Machine

In order to run Marketing Factory, you first need to install an Oracle's Java SE (Java Platform, Standard Edition) 8 on your system. Marketing Factory requires the JDK (Java Development Kit) package to run.

To check if Java is already installed on your system, type the following command line at the prompt of your system:

java -version

You should get a message indicating which Java version is installed on your system. Please note that the same message will be displayed if you only have a JRE installed. If an error is returned, you probably don't have a Java Platform installed.

If you have installed other versions of the Java Platform, Java Runtime Environment or other Java servers on your system, we recommend that you run a few checks before starting the installation in order to be sure that Digital Factory will run without problems.

If you need to obtain and install a new Java SE, you can find both Linux and Windows versions on the Oracle Web site:

To install a Java Virtual Machine on a Windows system, you need to have administrator rights on your computer. Please contact your system administrator if you don't have sufficient permissions.

Although the Context Server tries to detect the location of the installed Java SE, we recommend setting the JAVA_HOME environment variable explicitly to the directory, where you have installed the Java SE.

To setup this variable, follow the steps, described in next sections.

2.3.1 Under Windows

  1. Open the Control Panel, and the System option. In Windows 7 and Vista it is: Control Panel / System and Security / System / Advanced System Settings. Then, depending on your system:
    • Select the Advanced tab and click on the Environment Variables button (Windows 7/Vista/XP/2000)
    • Select the Properties tab and click on the Environment button (Windows NT)
  2. Click on New in the "System variables" section to add a new environment variable. Enter the following information:
    • Variable name: JAVA_HOME
    • Variable value: c:\Program Files\Java\jdk1.8.0_60 (replace this value with the correct path)

Click on OK to validate your entry. The Java Virtual Machine should now be correctly set-up. Please note that on Windows NT you will need to restart your computer to apply the changes.

2.3.2 Under Linux

Set the JAVA_HOME variable to the root directory of your JDK installation. Both examples below suppose you have installed the JDK version 1.8 in your /usr/java directory. The classpath is usually set by typing:

In bash or ksh:

export JAVA_HOME=/usr/java/jdk1.8

In csh or tcsh:

export JAVA_HOME /usr/java/jdk1.8

2.3.3 Under Solaris

Set the JAVA_HOME variable to the root directory of your JDK installation. Both examples below suppose you have installed the JDK version 1.8 in your /usr/java directory. The classpath is usually set by typing:

In ksh:

export JAVA_HOME=/usr/java

In sh:

JAVA_HOME=/usr/java;export $JAVA_HOME

In csh or tcsh:

setenv JAVA_HOME /usr/java

2.4 Digital Factory

Marketing Factory 1.0 requires an installation of a Digital Factory or later. For installation instructions and system requirements, please, refer to the Configuration and fine tuning Guide - Digital Factory document.

3 Installation

The Context Server official and nightly builds are distributed as packages (ZIP or TAR/GZ), which contain the Apache Karaf server with all the Unomi services bundled and pre-configured. A second distributable is the Marketing Factory Package itself (JAR file), which includes modules to be deployed on the Digital Factory 7.1 instance. Next sections describe the installation of both parts.

3.1 Context server

3.1.1 Compatibility

Depending on the Marketing Factory version that you are deploying on your DX Instance, you will need to get the compatible Unomi Context Server. This information should be on the Marketing Factory download page. The wrong version on Unomi will not work with Marketing Factory.

3.1.2 Installation

The installation of the Context Server consists of one unique step, which requires uncompressing the content of the context-server-package-X.X.X.tar.gz (Linux / Solaris / Mac OSX) or into your target installation folder. It will create the folder context-server-package-X.X.X, which we will reference later in this document as <cxs-install-dir>.

3.1.3 Directory layout

The directory layout of an installed Context Server (after first startup) is as follows:

  • /bin: control scripts to start, stop, login etc.
  • /data: working directory
    • /cache: OSGi framework bundle cache
    • /contextElasticSearch: Elasticsearch indexes
    • /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 Context Server. 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 next section).

3.1.4 Starting and stopping the Context Server

Context Server supports different start mode:

  • the regular mode starts CXS in foreground, including the shell console.
  • the server mode starts CXS in foreground, without the shell console.
  • the background mode starts CXS in background.

You can also manage CXS as a system service (see Integration in the operating system: the Service Wrapper section of the Apache Karaf documentation located here:

Various run modes are described in details on the Start, stop, restart, connect page ( of the Apache Karaf documentation.

For development, demo and quick test purposes the regular mode is appropriate, whereas for a production run the background mode is suited best. Regular mode

For Linux / Solaris / Mac OSX:


For Windows:


This starts CXS as a foreground process, and displays the shell console.

Note, please, closing the console or shell window will cause Context Server to terminate.

In regular mode you could type 'system:shutdown' or 'logout' in the console to shutdown CXS. Starting a CXS server in a background mode

For Linux / Solaris / Mac OSX:


For Windows:


You can connect to the shell console using SSH or client (see the next section). Connecting using a client

Even if you start CXS 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 to Context Server console remotely. To connect to the console, you can use the bin/client Unix script (bin\client.bat on Windows).

In order to connect to a local process you should use for Linux / Solaris / Mac OSX:

./bin/client -h localhost -u karaf

For Windows:

bin\client.bat -h localhost -u karaf Stopping Context Server

When you start Context Server in regular mode, the logout command or CTRL-D key binding logout from the console and shutdown the Context Server instance.

When you start Context Server 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 work 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.

3.2 Marketing Factory Package

3.2.1 Deploy modules

The Marketing Factory Package is delivered as a JAR with the name, like EnterpriseDistribution-MarketingFactory-1.0.0.jar, which has to be installed on your Digital Factory 7.1 server.

While your Digital Factory server is running go into the Server Administration UI _ System components _ Modules and use Upload action choosing the EnterpriseDistribution-MarketingFactory-1.0.0.jar file to install the package.

The package installs two module:

  • marketing-factory-core
  • marketing-factory-angular

3.2.2 Enable modules on your site

You should enable those two modules on a site, where you would like the Marketing Factory feature to be enabled:

  1. Use the Server Administration UI / Web Projects
  2. Choose your Web project and click on Edit site icon (second in the actions)
  3. Click on Choose modules to be deployed button
  4. On the next screen select the Marketing Factory Angular module (marketing-factory-angular) and Marketing Factory Core (marketing-factory-core) module and click Next to save the changes.

Now you could switch into Edit mode for the site and go to the Site Settings tab (left side panel in edit module). A new section will be available there, which contains Marketing Factory related management pages:

Please, refer to the next section for the description of how to setup Marketing Factory.

3.2.3 Setup

Now when the Marketing Factory modules are installed and enabled on your site, you could perform the setup, i.e. connect the Marketing Factory with the target Context Server instance, which should be also up and running at that point.

In the Edit mode navigate to the Site settings tag (left-side panel) of your site and open the Marketing Factory / Base settings screen. Here you should provide the following information:

  • Context Server Root URL: this should be the base administration URL of the context server. Usually something like http://localhost:8181 on a local install, or https://localhost:9443 if you have configured the context server using SSL (recommended).
  • (SSL only) Trust any certificate: activate this checkbox if you are using SSL connection and if you are using self-signed 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.
  • Context server user name: the context server requires a login to access the administration REST API. By default it is accessible with the "karaf" user.
  • Context server password: the default password for the "karaf" user is karaf.
    And click on a Save button.

    After the settings are successfully saved, the screen shows the configured Context Server instance:

On this step the setup of the Marketing Factory is finished and you could start managing the Web experience using various entry points in the Marketing Factory administration menu.

3.2.4  Roles and permissions

When deploying Marketing Factory modules, 3 permissions are added on the Editor in chief role.

if you have created your own role, you will have to add theses 3 permissions to access the Marketing Factory administration interface.

4 Configuring main Context Server features

This chapter covers the configuration of main features of the Context Server.

4.1 Changing the default configuration

If you want to change the default configuration, you can perform any modification you want in the <cxs-install-dir>/etc directory.

The context server configuration is kept in the <cxs-install-dir>/etc/org.apache.unomi.web.cfg file. It defines the addresses and ports where it can be found:


If you need to specify an Elasticsearch cluster name that is different than the default, it is recommended to do this

BEFORE you start the server for the first time, or you will lose all the data you have stored previously.

To change the cluster name, first create a file called <cxs-install-dir>/etc/org.apache.unomi.persistence.elasticsearch.cfg with the following contents:

And replace the parameter here by your cluster name.

You can also put an Elasticsearch configuration into a file <cxs-install-dir>/etc/elasticsearch.yml to customize it.

Please note that elasticsearch.yml is space sensitive and one space at the wrong place will break it. Here is the error you will get :
Error trying to load settings from file:/opt/unomi-1.0.1/etc/elasticsearch.yml: Failed to load settings from [file:/opt/unomi-1.0.1/etc/elasticsearch.yml] (activate debug mode for exception details)

If you want your context server to be a client only on a cluster of Elasticsearch nodes, just set the property to false (see 5.4 Cluster setup section for details).

4.2 Installing the MaxMind GeoIPLite2 IP lookup database

The Context Server requires an IP database in order to resolve IP addresses to user location. The GeoLite2 database can be downloaded at MaxMind from the following location:

Simply download the GeoLite2-City.mmdb file and copy it into the <cxs-install-dir>/etc directory.

4.3 Installing Geonames database

The Context Server includes a geocoding service based on the geonames database ( It can be

used to create conditions based on countries or cities. In order to use it, you need to install the Geonames database. Get the database from here:

Download it and put it in the <cxs-install-dir>/etc directory, without unzipping it.

Edit <cxs-install-dir>/etc/org.apache.unomi.geonames.cfg file and set request.geonamesDatabase.forceImport to true. The data import should start right away. Otherwise, import should start at the next startup. Import runs in background, but can take about 15 minutes.

At the end, you should have about 4 million entries in the geonames index.

4.4 Integrating with an Apache HTTP Web Server

In some production setup, you will often need to redirect the port 8181 and 8443 to the default HTTP (80) and HTTPS (443) ports. In order to do so, you will need to setup an Apache HTTP web server in front of Apache Unomi.

Here is an example configuration using mod_proxy and the DNS name

In your Unomi package directory, in /etc/org.apache.unomi.web.cfg:

Main virtual host config:

<VirtualHost *:80>
 Include /var/www/vhosts/
<IfModule mod_ssl.c>
 <VirtualHost *:443>
  Include /var/www/vhosts/ SSLEngine on
  SSLCertificateFile /var/www/vhosts/ 
  SSLCertificateKeyFile /var/www/vhosts/   
  SSLCertificateChainFile /var/www/vhosts/
  <FilesMatch "\.(cgi|shtml|phtml|php)$">
   SSLOptions +StdEnvVars
  <Directory /usr/lib/cgi-bin>
   SSLOptions +StdEnvVars
  BrowserMatch "MSIE [2-6]" \
   nokeepalive ssl-unclean-shutdown \
   downgrade-1.0 force-response-1.0
  BrowserMatch "MSIE [17-9]" ssl-unclean-shutdown 


DocumentRoot /var/www/vhosts/
CustomLog /var/log/apache2/ combined
<Directory />
 Options FollowSymLinks
 AllowOverride None 
<Directory /var/www/vhosts/>
 Options FollowSymLinks MultiViews 
 AllowOverride None
 Order allow,deny
 allow from all 
<Location /cxs>
 Order deny,allow
 deny from all
 allow from
 allow from
RewriteEngine On
RewriteRule .* - [F]
ProxyPreserveHost On
ProxyPass /server-status !
ProxyPass /robots.txt !
RewriteCond %{HTTP_USER_AGENT} Googlebot [OR]
RewriteCond %{HTTP_USER_AGENT} msnbot [OR]
RewriteCond %{HTTP_USER_AGENT} Slurp
RewriteRule ^.* - [F,L]
ProxyPass / http://localhost:8181/ connectiontimeout=20 timeout=300 ttl=120
ProxyPassReverse / http://locahost:8181

4.5 Cluster Setup

4.5.1 Discovery

Context Server relies on Elasticsearch to discover and configure its cluster, by using its built-in zen discovery module. For more information of various discovery modules, please, refer to: Multicast

For the multicast discovery you just need to install multiple Context Servers on the same network, and enable the discovery protocol in <cxs-install-dir>/etc/org.apache.unomi.persistence.elasticsearch.cfg file:

All nodes on the same network, sharing the same cluster name, will be part of the same cluster. Unicast

In production, it is recommended to use unicast instead of multicast (see This works by providing Elasticsearch a list of nodes that it should try to contact. Once the node contacts a member of the unicast list, it will receive a full cluster state that lists all nodes in the cluster. It will then proceed to contact the master and join.

The unicast is activated by disabling the multicast and providing a list of hosts (IP + port number) to contact. The following changes have to be applied to the <cxs-install-dir>/etc/org.apache.unomi.persistence.elasticsearch.cfg file:["", ""]

4.5.2 ElasticSearch Configuration

It is important to know that not all the settings from elasticsearch.yml are configurable in org.oasis_open.contextserver.web.cfg.

Here is the list of the only parameter supported in contextserver.web.cfg, the rest has to be done in elasticsearch.yml:


4.5.3 Recommended configuration

It is recommended to have one node dedicated to the Context Server, where the other nodes take care of the Elasticsearch persistence. The node, dedicated to the Context Server, will have set to false. 2 node cluster

In this setup one node is dedicated to Context Server whereas the other is for Elasticsearch indexes storage.

Node A (Context Server processing):

Node B (Elasticsearch data):
monthlyIndex.numberOfReplicas=0 3 node cluster

This setup features one node, dedicated to Context Server request processing, and two nodes for Elasticsearch data storage with full fault-tolerance.

Node A (Context Server processing):

Node B (Elasticsearch data node 1):

Node C (Elasticsearch data nodea 2):

4.5.4 Cluster troubleshooting

In order to monitor the state of your Unomi Cluster, 2 URLs are quite useful:

  • http://<UnomiNode1>:9200/_cluster/health?pretty=true : This command retrieves the health of your Unomi cluster (green is good). If you face communication issues between your cluster nodes, it will be orange or red. Make sure that all the nodes of your cluster are started in order to get a better idea of your cluster health.
  • http://<UnomiNode2>:9200/_cluster/state?pretty=true : This command gives you a detailed state of your Unomi node in the cluster.
When you start the first node of your elastic search cluster, if the replica is set to more than one it is normal to get an error in the log. The first node is not able to replicate the data into other nodes and you get the following error message :
Caused by: org.elasticsearch.action.UnavailableShardsException: [context][1] Not enough active copies to meet write consistency of [QUORUM] (have 1, needed 2). Timeout: [1m], request: index

4.5.5 Clustering on Amazon Web Service

One critical thing when setting up Unomi clusters on EC2 is the value of in elasticsearch.yml. The trick is to use the VPN/internal IP as network host (I used the logical host value " _eth0:ipv4_ ( to be sure to get the right IP if it's dynamic and the public IP in the unicast discovery. The default value doesn't work on AWS.

4.6 Security aspects

4.6.1 Administrator username and password

The Context Server REST API is protected using JAAS authentication and using Basic or Digest HTTP auth. By default, the login/password for the REST API full administrative access is "karaf/karaf".

It is strongly recommended that you change the default username and password as soon as possible.

This can be done by modifying the following configuration file <cxs-install-dir>/etc/

karaf = karaf,_g_:admingroup
_g_\:admingroup = group,admin,manager,viewer,webconsole

In-depth details for the JAAS security in the CXS' Karaf server can be found at:

4.6.2 SSL certificate

The Context Server package is configured with a default SSL certificate. You can change it by following these steps:

  1. Replace the existing keystore in file <cxs-install-dir>/etc/keystore by your own certificate. See for details.
  2. Update the keystore and certificate password in <cxs-install-dir>/etc/ file: = true

You should now have SSL setup on the Context Server with your certificate, and you can test it by trying to access it on port 9443.

4.6.3 Securing a production environment

Before going live with a project, you should absolutely read the following sections that will help you setup a proper secure environment for running your Context Server. Install and configure a firewall (port numbers)

You should setup a firewall around your cluster of context servers and/or Elasticsearch nodes. If you have an application-level firewall you should only allow the following connections open to the whole world:

  • http://localhost:8181/context.js
  • http://localhost:8181/eventcollector

All other ports should not be accessible to the world. For your Context Server client applications (such as the Jahia Marketing Factory), you will need to make the following ports accessible:

  • 8181 - Context Server HTTP port
  • 9443 - Context Server HTTPS port

For your Context Servers and for any standalone Elasticsearch nodes you will need to open the following ports for proper node-to-node communication:

  • 9200 - Elasticsearch REST API
  • 9300 - Elasticsearch TCP transport

Of course, any ports listed here are the default ports configured in each server, you may adjust them if needed in the Network And HTTP section of the <cxs-install-dir>/etc/elasticsearch.yml file.

Note that if you need a temporary SSL certificate for a pre-production environment for example, you can generate one using Certbot ( until a proper one is delivered from IT. Secure Elasticsearch

Follow industry recommended best practices for securing Elasticsearch. You may find more valuable recommendations here: Setup a proxy

As an alternative to an application-level firewall, you could also route all traffic to the context server through a proxy and use it to filter any communication.

4.6.4 Search robots and crawlers

By default the Context Server includes a /robots.txt file with the following content:

User-agent: *
Disallow: /

meaning, it disallows search bots and crawlers to access the content.

On top of it you could block the known search bots on your front-end Apache HTTPD server using the following rewrite rules:

RewriteCond %{HTTP_USER_AGENT} Googlebot [OR]
RewriteCond %{HTTP_USER_AGENT} msnbot [OR]
RewriteCond %{HTTP_USER_AGENT} Slurp
RewriteRule ^.* - [F,L]

4.7 Marketing Factory & Remote Publication

Jahia Marketing Factory is fully compatible with a remote publishing architecture. Though a precise method must be applied. Here are the steps:

  1. start the context server / unomy
  2. start DX: both contribution / remote server in "development mode" (

On the contribution server:

  1. create the desired site (eg. ACME SPORT)
  2. install and enable the MF-modules
  3. configure MF in site settings

On the remote server:

  1. create a new site with the same template set
    remote site must have the same name/sitekey as original site, as all goals/conditions are based on node paths. Different site names are NOT supported for now.
  2. install MF-modules
    do NOT activate MF-modules for this site
  3. Then set up the remote publication on the contribution node and execute (check logs / should be good)
  4. stop both DX-server
  5. set contribution node to operationMode=production (
  6. set remote server has to be set to "operatingMode=distantPublicationServer" (
  7. restart
  8. Open remote site in a new private window and browse the page
  9. Back in site settings / MF (contribution node) check that the profile was created - OK.

5 Maintenance and upgrades

5.1 Logging

The logging is configured in the <cxs-install-dir>/etc/org.ops4j.pax.logging.cfg file, so that by default the logging it routed into the <cxs-install-dir>/data/log/karaf.log file.

More details on how to tune logging settings and also on the log-related console commands is given here:

One of the most useful console commands (especially in development) is:


which continuously displays the log entries in the console.

5.2 How to backup Context Server?

Backing up your system is useful in many cases as it minimizes the risk of losing all of your data and a backup is a mandatory step in case of an upgrade or migration process.

The Context Server by default is configured to write its runtime data into the <cxs-install-dir>/data folder, so in that sense it is a self-contained installation.

There are several backup types, which serve different purposes:

  1. Full Context Server backup: is done by archiving the whole <cxs-install-dir>/ folder, whereas the Context Server process is stopped.
  2. Configuration backup: is done by archiving the <cxs-install-dir>/etc folder. Usually done, before/after planned configuration updates.
  3. Runtime data backup: is performed by archiving the <cxs-install-dir>/data folder. Useful for incremental (nightly) backups and allows rolling back to a previous stable/consistent state in case of data corruption/loss.

In order to trigger the data replication to a new node (for the sake of a backup), you could start a new Context Server cluster node with parameters (see chapter 5.4Cluster setup):

After startup this node will start receiving replicated Elasticsearch data from other nodes. After the replication is done, you can stop this node and will have the full backup.

5.3 Upgrading Context Server

In order to upgrade Context Server to a new version or migrate the data to a new installation it is right now sufficient to perform the following steps:

  1. Stop the old Context server
  2. Install a new version (or a new copy) of the Context Server
  3. Copy the following folder from the old installation into a new one: <cxs-install-dir>/data/contextElasticSearch
  4. Apply any custom changes in the configuration (file in the <cxs-install-dir>/etc folder) to a new instance of the Context Server
  5. Start the new instance of the Context Server to complete the migration.