Should you have questions, please do not hesitate to contact us as mentioned on our website (http://www.jahia.com).

2 Prerequisites

2.1 Introduction

Let’s first look at an example of a typical architecture diagram:

Note: in the above schema, when there are arrows between groups of nodes, it means that these arrows actually go to each node, but are not repeated to make the diagram easier on the eyes.

Basically you can see four layers of nodes:

Apache Web HTTP servers: usually a single node can be used, but it is also possible to setup a cluster of web servers. It will be used to proxy the requests to the DX and Unomi nodes, as well as protect the resources from being accessed from the open web. It is also a good idea to use HTTPS to proxy the requests, so that all the external traffic only uses HTTPS, while the "internal" traffic may use HTTP or HTTPS. Currently Apache Unomi only supports HTTP for the public endpoint, so you will need to setup HTTPS-to-HTTP proxying using Apache HTTP (or another equivalent) if you need to have your public traffic secured.

DX nodes: these are instances of the CMS that have the Marketing Factory modules deployed on them. They communicate between each other using Karaf Cellar (starting with DX 7.2) which itself uses Hazelcast as the library for node-to-node communication.

Apache Unomi nodes: the Unomi nodes also use Karaf Cellar and Hazelcast to communicate, but also use JMX to retrieve node health information and communicate it back to the Marketing Factory modules for load distribution and configuration.

ElasticSearch nodes: the ES nodes use the custom networking protocol specific to ElasticSearch to communicate both between ES nodes and Unomi nodes.

Please note that in order to reduce the amount of hardware needed, it is possible to deploy the Unomi and ElasticSearch nodes on the same (physical or virtual) machines, meaning that in the above graph only 6 (physical or virtual) machines could be used. However in high load scenarios, it might be interesting to separate each node in order to be able to better control the resources the nodes need and maximize resistance to failure.

2.1.1 Ports used

As illustrated in the cluster diagram, a collection of ports is used by a typical Marketing Factory installation. The following summary table lists the ports that will need to be open in firewalls at various layers in the deployment to make sure everything will work as expected.

Port

Name

Visibility

Type

Description

1099

JMX over RMI

Unomi

TCP

Used by Apache Unomi to exchange JVM information to provide cluster health information

44444

JMX over RMI

Unomi

TCP

Server port used by Unomi to retrieve cluster node information

5700-5800

Hazelcast

Unomi

TCP

Used by Apache Karaf Cellar to keep track of cluster nodes and exchange configuration information

Apache Unomi Administration endpoint, used to manage all Apache Unomi objects (segments, profile editing, etc…), also the Unomi secure address (Endpoint used in a secure environment)

9200

ElasticSearch HTTP

DX

TCP

ElasticSearch HTTP interface, used by clients such as Kibana or other applications

9300

ElasticSearch Transport

Unomi

TCP

ElasticSearch Transport TCP interface, highly optimized, used by Apache Unomi to talk to ElasticSearch, as well as between ElasticSearch nodes to exchange data (replications, …)

The visibility column describes the highest layer the application architecture that must have visibility to that port. So for example for port 8181, a "Web" visibility indicates that the port must be visible to the world, although this doesn’t mean it necessarily is exposed directly, it could still be relayed through a proxy (for an example with Apache mod_proxy, see section 4.4)

ATTENTION: If you are deploying Marketing Factory in a network where there are already other instances of Apache Unomis and ElasticSearch servers, you must change the cluster name in the ElasticSearch instances as well as modify ports so that you do not join an existing different cluster. This is very important because data corruption may occur if not setup properly!

2.1.2 Solution overview

Now let’s look at an overview of the elements that compose Marketing Factory.

Apache Unomi: an open source personalization and A/B testing server that is an implementation of the OASIS Context Server specification. Throughout this document we will refer to it as "Apache Unomi". Jahia distributes a custom package of Apache Unomi for integration with Marketing Factory that is tested and supported and that must be paired with the corresponding version of the Marketing Factory DX modules. Apache Unomi is responsible for data collection, rule execution, and serving the personalization context back to the Marketing Factory components so they may build personalized experiences. Apache Unomi itself has the following sub-components:

Apache Karaf: an OSGi runtime that contains a lot of enterprise ready features such as fine-grained logging, clustering, SSH shell console, provisioning, server-side REST framework (CXF) and many more advanced enterprise capabilities. You might think of it as the equivalent of what Tomcat is to Web Application Server but in this case for OSGi Application servers. It is a standalone package that is executed within a Java Virtual Machine.

CXS API: The Context Server API is an implementation of the on-going work of the OASIS Context Server Technical Committee to define a standardized API to collect and serve personalization and A/B testing data. As the specification is still not completed, this API might change but both Marketing Factory and Apache Unomi will be adapted to follow any modifications.

Apache Unomi OSGi bundles: these are the actual components that implement the services that are exposed by the CXS API. They range from cluster management to data collection, rules processing, profile and session management and many other back ends that deliver the personalization and A/B testing functionality.

ElasticSearch: Apache Unomi uses ElasticSearch to store, index and retrieve all the objects that are needed to deliver personalization and A/B testing. All the events, profiles, sessions, definitions, … are stored as JSON documents within the ElasticSearch cluster. As ElasticSearch can scale to dozens or sometimes even hundreds of nodes, it offers a highly scalable data and search back-end.

2.2 Minimal System Requirements

Please find below the minimum system requirements to properly run Marketing Factory. You can refer to the document ‘Marketing Factory performances metrics" for more information about system requirements & sizing. This document can be requested to the sales or support team.

OS:

Windows

Linux

Solaris

Mac OSX

Suggested Min. Production Environments:

Quad Core (64 bit CPU and OS)

8 GB RAM

100 GB HDD (SSD recommended)

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) in version 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: http://www.oracle.com/technetwork/java/javase/downloads/index.html. 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 Apache Unomi 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

i) 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) ii) 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:

3 Installation

The Apache Unomi official and nightly builds are distributed as packages (ZIP or TAR/GZ), which contain the Apache Karaf server with all the Apache 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 Experience Manager instance. Next sections describe the installation of both parts.

3.1 Elasticsearch server

Marketing Factory 1.7 works with Apache Unomi 1.1.2-Jahia that requires ElasticSearch 5.1.2. Therefore you will need to install a standalone ElasticSearch using the following steps:

3.1.1 Starting and stopping ElasticSearch

Change to the <elasticsearch-install-dir>/bin and launch ElasticSearch simply by using the command:

./elasticsearch

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 we will need it running before starting Apache Unomi. 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

3.2 Apache Unomi

3.2.1 Compatibility

Depending on the Marketing Factory version that you are deploying on your DX Instance, you must get the compatible corresponding Apache Unomi. This information should be on the Marketing Factory download page. Do not download Apache Unomi directly from the public Apache website as these versions are not supported. Marketing Factory will not work if it used with a non-compatible version of Apache Unomi

3.2.2 Installation

As a reminder, you can find the Jahia supported version of Unomi on jahia.com website. The installation of Apache Unomi 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 context-server-package-X.X.X.zip 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>. Whether you’re installing Unomi and ElasticSearch locally, remotely, in cluster or not, you need to specify an ElasticSearch cluster name, 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. You can also change the host and port if they need to be modified from the default values.

ATTENTION: If you are installing multiple Apache Unomi clusters (for example pre-production and production) in the same network, you have to ensure that the cluster name is different between the environments, otherwise you will connect all the nodes together!

To change these settings, you will need to modify for each cluster node a file called <cxs-install-dir>/etc/org.apache.unomi.persistence.elasticsearch.cfg with the following contents:

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
elasticSearchAddresses=localhost:9300
index.name=context

ATTENTION: Please note that elasticsearch.yml is space sensitive and one space at the wrong place will break it.

3.2.3 Directory layout

The directory layout of an installed Apache Unomi (after first startup) is as follows:

/bin: control scripts to start, stop, login etc.

/data: working directory

/cache: OSGi framework bundle cache

/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 Apache Unomi. 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). You will also want to clear the <elasticsearch-install-dir>/data directory if you want to purge the stored data.

3.2.4 Starting and stopping Apache Unomi

Apache Unomi 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: 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, whereas for a production run the "background" mode is suited best.

3.2.4.1 Regular mode

For Linux / Solaris / Mac OSX:

./bin/karaf

For Windows:

bin\karaf.bat

This starts CXS as a foreground process, and displays the shell console. Note, please, closing the console or shell window will cause Apache Unomi to terminate. In regular mode you could type 'system:shutdown' or 'logout' in the console to shutdown CXS.

3.2.4.2 Starting a CXS server in a background mode

For Linux / Solaris / Mac OSX:

./bin/start

For Windows:

bin\start.bat

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

3.2.4.3 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 the Apache Unomi 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

3.2.4.4 Stopping Apache Unomi

When you start Apache Unomi in regular mode, the logout command or CTRL-D key binding helps you logout from the console and shutdown the Apache Unomi instance. When you start Apache Unomi 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.

3.3 Marketing Factory Package

3.3.1 Deploy modules

The Marketing Factory Package is delivered as a JAR named EnterpriseDistribution-MarketingFactory-1.7.0.jar, which must be deployed on your Digital Experience Manager server. While your Digital Factory server is running, go into the Server Administration UI _ System components _ Modules and use the "Upload action" choosing the EnterpriseDistribution-MarketingFactory-1.7.0.jar file to install the package. The package installs three modules: - marketing-factory-core - marketing-factory-angular - marketing-factory-components

3.3.2 Enable the modules on your site

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

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.3.3 Setup

Once the Marketing Factory modules are installed and enabled on your site, the next step is to connect the Marketing Factory modules to the Apache Unomi instance, which should be also up and running at that point. In the Edit mode navigate to the Site settings tab (left-side panel) of your site and open the Marketing Factory Settings screen. Here you should provide the following information:

Apache Unomi Root URL: this should be the base administration URL of Apache Unomi. This address must use https protocol, for instance: https://localhost:9443 . See section 4 for more information about Unomi addresses configuration.

Trust any ssl certificate: 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 Apache Unomi package is configured with a default SSL certificate.

Apache Unomi user name: Apache Unomi requires a login to access the administration REST API. By default it is accessible with the "karaf" user.

Apache Unomi password: the default password for the "karaf" user is "karaf".

Time out in milliseconds: this value defines the default Javascript timeout for request going from the Marketing Factory modules to Apache Unomi. If Apache Unomi doesn’t answer to requests fast enough, and the timeout value is reached, the modules will fallback to default variants and behave "cleanly" under the circumstances. This helps protect the system against network issues or potential Apache Unomi slowdowns or failures. The value of the timeout is a balance to find between your organization expectations on the response time of the content and the infrastructure.

The default value is 1500ms which is adapted to local environments where Unomi typically respond in this delay. For production installations, we recommend to set this value so that it doesn't downgrade the customer experience while still being reasonable in your environment. Our tests show that 300ms is a good balance.

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

4.3 Installing Geonames database

Apache Unomi includes a geocoding service based on the geonames database (http://www.geonames.org/). 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 "allCountries.zip" 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" ElasticSearch index.

4.4 Integrating with an Apache HTTP Web Server

In some production setup, you will often need to redirect the port 8181 and 9443 to the default HTTP (80) and HTTPS (443) ports. 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 "unomi.apache.org":

4.5 Cluster Setup

4.5.1 Discovery

Discovery must be configured on every layer of the cluster architecture. In this document we will only detail the discovery configuration that is possible for the Marketing Factory elements, that is to say the Apache Unomi and ElasticSearch components. For DX cluster discovery setup, please refer to the DX "Configuration and Fine Tuning Guide" documentation. Apache Unomi relies on Apache Karaf Cellar, which in turn uses Hazelcast to discover and configure its cluster. You just need to install multiple Apache Unomis on the same network, and then (optionally) change the Hazelcast configuration in the following file: <cxs-install-dir>etc/hazelcast.xml
All nodes on the same network, sharing the same cluster name will be part of the same cluster. You can find more information about how to configure Hazelcast here: http://docs.hazelcast.org/docs/3.4/manual/html/networkconfiguration.html For the actual ElasticSearch configuration however, this must be done using the following file:<elasticsearch-install-dir>/config/elasticsearch.yml
The documentation for the various discovery options and how they may be configured is available here: https://www.elastic.co/guide/en/elasticsearch/reference/current/modules-discovery.html Depending on the cluster size, you will want to adjust the following parameters to make sure your setup is optimal in terms of performance and safety. Here is an example of a typical ElasticSearch cluster configuration:

4.5.1.2 Multicast

Multicast makes it easier to setup cluster node in an "automatic" discovery, which can be very useful for setting up environments quickly such as test environments. However it is not recommended for production or even environments where multiple installs might co-exist in the same network, unless the installers have some solid experience with multicast network setups.

4.5.1.2.1 Apache Unomi

For multicast configuration in Apache Unomi, you will need to modify the <cxs-install-dir>/etc/hazelcast.xml file, more specifically the following section:

4.5.1.3.2 ElasticSearch

In production, it is recommended to use unicast instead of multicast (see https://www.elastic.co/guide/en/elasticsearch/guide/current/_important_configuration_changes.html#_prefer_unicast_over_multicast). 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 protocol 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 <elasticsearch-install-dir>/config/elasticsearch.yml file:

4.5.2.1 2 node cluster

In this setup we don’t have enough ElasticSearch nodes to properly benefit from replicas (notably because of their impact on performance) so we deactivate them. Node A:

numberOfReplicas=0
monthlyIndex.numberOfReplicas=0

Node B:

numberOfReplicas=0
monthlyIndex.numberOfReplicas=0

4.5.2.2 3 node cluster

This setup sets up one replica since we have enough nodes to be able to use replicas without affecting performance too much. Node A:

numberOfReplicas=1
monthlyIndex.numberOfReplicas=1

Node B:

numberOfReplicas=1
monthlyIndex.numberOfReplicas=1

Node C:

numberOfReplicas=1
monthlyIndex.numberOfReplicas=1

4.5.3 Cluster troubleshooting

In Apache Unomi, you might want to look at the cluster command lines available in Apache Karaf. Depending on how you launched Karaf, you may either use them directly on the console, or through an SSH connection to the server. To connect through SSH simply do:

ssh –p 8101 karaf@unomi

The default password is "karaf". You should really change this upon installation by modifying the <cxs-install-dir>/etc/users.properties file. To get a list of available commands, simply type on the command line:

help

In order to monitor the state of your Unomi ElasticSearch Cluster, 2 URLs are quite useful: - Error! Hyperlink reference not valid. : This command retrieves the health of your ElasticSearch 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. - Error! Hyperlink reference not valid. : This command gives you a detailed state of your Unomi node in the cluster.

ATTENTION: When you start the first node of your ElasticSearch 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

ATTENTION: The following WARN could also be displayed:[2017-02-08T10:15:23,571][WARN ][o.e.d.z.ElectMasterService] [RlyE1OZ] value for setting "discovery.zen.minimum_master_nodes" is too low. This can result in data loss! Please set it to at least a quorum of master-eligible nodes (current value: [-1], total number of master-eligible nodes used for publishing in this round: [2])
Please refer directly to ElasticSearch documentation for more information: https://www.elastic.co/guide/en/elasticsearch/reference/current/modules-discovery-zen.html

4.5.4 Clustering on Amazon Web Service

One critical thing when setting up ElasticSearch clusters on EC2 is the value of network.host in <elasticsearch-install-dir>/config/elasticsearch.yml. The trick is to use the VPN/internal IP as network host (For instance, network.host: _eth0:ipv4_" - see https://www.elastic.co/guide/en/elasticsearch/reference/1.6/modules-network.html) to be sure to get the right IP if it’s dynamic and the public IP in the unicast discovery. The default value "192.168.0.1" doesn’t work on AWS.

4.6 Security aspects

4.6.1 Administrator username and password

The Apache Unomi 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/users.properties:

4.6.2 SSL certificate

The Apache Unomi 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 http://wiki.eclipse.org/Jetty/Howto/Configure_SSL for details. 2. Update the keystore and certificate password in <cxs-install-dir>/etc/custom.properties file:

You should now have SSL setup on Apache Unomi 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 Apache Unomi.

4.6.3.1 Install and configure a firewall (port numbers)

You should setup a firewall around your cluster of Apache Unomis 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 Apache Unomi client applications (such as the DX Marketing Factory), you will need to make the following ports accessible to the client machine:

8181 - Apache Unomi HTTP port

9443 - Apache Unomi HTTPS port For your Apache Unomis and for any standalone ElasticSearch nodes you will need to open the following ports for proper node-to-node communication:

1099 - RMI JMX port

44444 - RMI JMX port

5700 - 5800 Hazelcast cluster protocol

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 <elasticsearch-install-dir>/config/elasticsearch.yml file or in the <cxs-install-dir>/etc property files.

Note that if you need a temporary SSL certificate for a pre-production environment for example, you can generate one using Certbot (https://github.com/certbot/certbot) until a proper one is delivered from IT.

4.6.3.2 Secure Elasticsearch

Follow industry recommended best practices for securing ElasticSearch. You may find more valuable recommendations here:

4.6.3.3 Setup a (SSL) proxy

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

A relatively straight-forward way to do this is to use an Apache HTTP server in front of the public-facing Apache Unomi endpoint. You could even setup this proxy connection to use SSL-only and proxy to the http://UNOMI_HOST:8181/ port. Configuration could look something like this:

ATTENTION: 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.

Create the desired site (eg. ACME SPORT)

Install and enable the MF-modules

Configure MF in site settings On the remote server:

Create a new site with the same template set

Install MF-modules

ATTENTION: do NOT activate MF-modules for this site

Then set up the remote publication on the contribution node and execute (check logs / should be good) - Stop both DX-server - Set contribution node to "operationMode=production" (jahia.properties) - Set remote server has to be set to "operatingMode=distantPublicationServer" (jahia.properties) - Restart - Open remote site in a new private window and browse the page - Back in site settings / MF (contribution node) check that the profile was created - OK.

4.8 Email action configuration

In Marketing Factory Rules, an action is available to send email. The emails will be sent using an SMTP server that needs to be configured in the following Apache Unomi file : /etc/org.apache.unomi.plugins.mail.cfg

In the email template, you can use the following pattern to display any profile property value in the email that will be sent: $profile.properties.("propertyId")$

This feature should never be used to send massive emails or for marketing campaign purposes. To integrate with email marketing or marketing automation tools, please contact your account manager.

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: https://karaf.apache.org/manual/latest/#_log. One of the most useful console commands (especially in development) is:

log:tail

which continuously displays the log entries in the console.

5.2 How to backup Apache Unomi?

Backing up your system is useful in many cases as it minimizes the risk of losing all your data and a backup is a mandatory step in case of an upgrade or migration process. Apache Unomi by default is configured to write its runtime data directly into the ElasticSearch server, which itself writes information in its <elasticsearch-install-dir>/data directory. There are several backup types, which serve different purposes:

Full Apache Unomi and ElasticSearch backup: is done by archiving the whole <cxs-install-dir>/ and <elasticsearch-install-dir> folders, with Apache Unomi and ElasticSearch processes stopped.

Runtime data file system backup: is performed by archiving the <elasticsearch-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 Apache Unomi cluster node with parameters (see chapter "4.4 Integrating with an Apache HTTP Web Server)

After startup, this node will start receiving replicated ElasticSearch data from other nodes. After the replication is done, you can stop this node. It contains the full backup.

5.3 Upgrading Apache Unomi

To check if there is any specific instruction related to the upgrade, please check our extranet documentation for upgrading between versions of Apache Unomi. Below are the usual steps :

5.3.1 Between minor versions (X.X.Y -> X.X.Z)

In order to upgrade Apache Unomi 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 Apache Unomi

2. Stop the ElasticSearch server

3. Install a new version (or a new copy) of Apache Unomi

4. Install a new version of the ElasticSearch version corresponding to the new version of Apache Unomi (if necessary)

5. Copy the following folder from the old installation into a new one: <elasticsearch-install-dir>/data

6. Apply any custom changes in the configuration (file in the <cxs-install-dir>/etc folder) to a new instance of Apache Unomi