Prerequisites

This topic provides an architecture diagram, ports typically used in a jExperience install, requirements, and shows how to set up a JVM.

Architecture diagram

The following architecture diagram shows layers and ports for a typical jExperience install. The typical install contains the following layers:

Apache Web HTTP servers
Usually a single node can be used, but you can also setup a cluster of web servers. It will be used to proxy the requests to the Jahia and jCustomer 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, jCustomer 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.
Jahia nodes
These are instances of the CMS that have the jExperience modules deployed on them. They communicate between each other using Karaf Cellar which itself uses Hazelcast as the library for node-to-node communication.
jCustomer nodes
The jCustomer nodes also use Karaf Cellar and Hazelcast to communicate.
Elasticsearch nodes
The Elasticsearch nodes use the custom networking protocol specific to Elasticsearch to communicate both between Elasticsearch nodes and jCustomer nodes.

Note: In the schema, arrows between groups of nodes indicate a relationship to each node. Arrows are not repeated to make the diagram easier to understand.

Note that in order to reduce the amount of hardware needed, it is possible to deploy the jCustomer and Elasticsearch nodes on the same (physical or virtual) machines, meaning that in the above diagram 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.

Ports required for a typical jExperience install

As shown in the cluster diagram, a collection of ports is used by a typical jExperience installation. The following summary table lists the ports that need to be open in firewalls at various layers in the deployment to ensure that jExperience works as expected.

Port	Name	Visibility	Type	Description
5700-5800	Hazelcast	jCustomer	TCP	Used by Apache Karaf Cellar to keep track of cluster nodes and exchange configuration information
8181	jCustomer Public (HTTP)	Web	TCP	jCustomer Public endpoint (exposed to the Internet) for event collection and context serving (for example profile, session, and segments)
9443	jCustomer Admin (HTTPS)	Jahia	TCP	jCustomer Administration endpoint, used to manage all jCustomer objects (for example segments and profile editing), also the jCustomer secure address (Endpoint used in a secure environment)
9200	Elasticsearch HTTP	Jahia	TCP	Elasticsearch HTTP interface, used by jCustomer to talk to ElasticSearch and also used by other clients such as Kibana or other applications
9300	Elasticsearch Transport	jCustomer	TCP	Elasticsearch Transport TCP interface, highly optimized, used by Elasticsearch nodes to exchange data (for example 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 How to configure Jahia to run behind Apache HTTP Server (httpd))

Warning: If you deploy jExperience in a network where there are already other instances of jCustomer and Elasticsearch servers, you must change the cluster name in the Elasticsearch instances and 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!

Requirements

This topic lists requirements for jCustomer. jExperience requires an installation of Jahia. For information on installing Jahia, see Installing, configuring and monitoring Jahia.

For Jahia requirements, refer to Prerequisites and system requirements.
For Elasticsearch requirements, see https://www.elastic.co/guide/en/elasticsearch/guide/current/deploy.html.

Minimal system requirements

Find below the minimum system requirements to properly run jExperience. You can refer to the jExperience performance metrics document for more information about system requirements & sizing. This document can be requested from the sales or support team.

Windows
Linux
Solaris
Mac OSX

Suggested minimum production environments

Quad Core (64 bit CPU and OS)
8 GB RAM
100 GB HDD (SSD recommended)

Setting up a Java Virtual Machine

To run jExperience, you first need to install an Oracle’s Java SE (Java Platform, Standard Edition) version 8 on your system. jExperience requires the JDK (Java Development Kit) package to run. Note that it is also possible to use Java SE version 11 now, but Java 8 is still the preferred version currently (will change in future jExperience releases).

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. Note that the same message displays 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 Jahia 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 must have administrator rights on your computer. Contact your system administrator if you don’t have sufficient permissions. Although jCustomer tries to detect the location of the installed Java SE, we recommend setting the JAVA_HOME environment variable explicitly to the directory, where you installed the Java SE. To setup this variable, follow the steps below.

Setting the JAVA_HOME environment variable in Windows

To set the JAVA_HOME environment variable in Windows:

Open the Control Panel, and the System option. In Windows 7 and Vista, navigate to Control Panel>System and Security>System>Advanced System Settings. Then, depending on your system:
- Select the Advanced tab and click Environment Variables (Windows 7,Vista,XP, 2000).
- Select the Properties tab and click Environment (Windows NT).
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 OK to validate your entry.

The Java Virtual Machine should now be correctly set-up. Note that on Windows NT you must restart your computer to apply the changes.

Setting the JAVA_HOME environment variable in 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

Setting the JAVA_HOME environment variable in Solaris

export JAVA_HOME=/usr/java

In sh:

JAVA_HOME=/usr/java;export

In csh or tcsh:

setenv JAVA_HOME /usr/java

Jahia

jExperience requires an installation of Jahia. For Jahia installation instructions and system requirements, see Installing, configuring and monitoring Jahia.