Using jCustomer docker image

October 8, 2024

The jahia/jcustomer image is used to run development, test, and production workload. Its resource allocation depends on the use case.

Instructions in this page are focused on the docker images provided with jCustomer 1.6.0 and above, older versions might require slight adjustments in the use of environment variables.

Pull command docker pull jahia/jcustomer:1.6.0
Exposed port 8181 (HTTP), 9443 (HTTPs), 8102, 5002 (when debugging is enabled)
Min/Max memory 2GB/8GB
vCPU requirements 2/4 vCPUs
Volume none

Quick start with docker-compose

Since jCustomer requires Elasticsearch to be running, we will be starting the environment with docker-compose.

In a folder of your choice, create a docker-compose.yml file.

version: '3.6'
services:
  elasticsearch:
    image: docker.elastic.co/elasticsearch/elasticsearch:7.12.1
    environment:
      - discovery.type=single-node
      - cluster.name=contextElasticSearch
    ports: # Expose Elasticsearch ports
      - "9200:9200"

  jcustomer:
    image: jahia/jcustomer:1.6.0
    container_name: jcustomer
    environment:
      - UNOMI_ELASTICSEARCH_ADDRESSES=elasticsearch:9200
    ports:
      - 8181:8181
      - 9443:9443
      - 8102:8102
    links:
      - elasticsearch
    depends_on:
      - elasticsearch

Then, from the same folder, open a terminal and enter the following command:

$ docker-compose up

Environment variables

The following environment variables can be provided when starting a jCustomer container.

Environment variable Default Description
JCUSTOMER_MAXMIND_GEOIP2_CITY_DATABASE_URL   URL to a Maxmind city database provided as a tar.gz file. During startup, jCustomer will download the database from this URL. 
JCUSTOMER_GEONAMES_ALL_COUNTRIES_ARCHIVE_URL   URL to the list of all countries as a zip file. During startup, jCustomer will dowload the database from this URL and place it in $JCUSTOMER_HOME/etc/allCountries.zip 
JCUSTOMER_DEBUG false To activate jCustomer karaf remote debugging on port 5005
UNOMI_ELASTICSEARCH_ADDRESSES localhost:9200 Host and port of the elasticsearch cluster
UNOMI_CLUSTER_PUBLIC_ADDRESS http://localhost:8181 URL to be used for reaching jCustomer using its publicly reachable interface
UNOMI_CLUSTER_PRIVATE_ADDRESS https://localhost:9443 URL to be used for reaching jCustomer on its private interface, this is used mostly for management. For example jExperience will communicate with jCustomer using that interface.
UNOMI_ROOT_PASSWORD karaf Root password to jCustomer
UNOMI_HAZELCAST_TCPIP_MEMBERS 127.0.0.1 jCustomer nodes can be deployed in a cluster, use this environment variable to specify a comma-separated list of hosts (IP or name) to be part of the cluster.
UNOMI_* n/a Additionally to the environment variables provided above, jCustomer supports all of Apache Unomi environment variables as detailed here.
JAVA_MAX_MEM 2048M Max MEM to be used by Java
JCUSTOMER_HOME /opt/jcustomer jCustomer home folder within the container. You will rarely need to modify this value.
KARAF_OPTS -Dunomi.autoStart=true Karaf opts used during startup

jCustomer 1.5.7 and below

The table below highlights environment variables that were available with jCustomer 1.5.7 and below.  

Environment variable Default Description
MAXMIND_KEY   The MAXMIND API key to fetch GeoLite DB (see https://dev.maxmind.com/geoip/geoip2/geolite2/). If not provided, the db won't be fetched.
unomi_env_var_UNOMI_ELASTICSEARCH_ADDRESSES   example: elasticsearch:9300
unomi_env_var_UNOMI_ELASTICSEARCH_CLUSTERNAME   example: docker-cluster
unomi_env_var_UNOMI_CLUSTER_PUBLIC_ADDRESS   example: http://public.address
unomi_env_var_UNOMI_CLUSTER_PRIVATE_ADDRESS   example: http://private.address
unomi_env_var_JAVA_MAX_MEM 1G  
unomi_env_var_UNOMI_ROOT_PASSWORD    
unomi_env_var_UNOMI_HAZELCAST_TCPIP_MEMBERS   example: unomi1,unomi2,unomi3
unomi_env_var_UNOMI_*   Additionally to the environment variables provided above, jCustomer supports all of Apache Unomi environment variables as detailed here.

Upgrading jCustomer

Migrating from old (1.5.7-) to new (1.6.0+) containers 

In general, migrating between docker images built differently requires attention to the internal filesystem structure, the database connection, and environment variables.  The internal filesystem and the database connection have not been modified and the two types of images are using entirely different (and non-conflicting) environment variables.

This means you could declare both unomi_env_var_UNOMI_ELASTICSEARCH_ADDRESSES and UNOMI_ELASTICSEARCH_ADDRESSES for use with a 1.5.7 or a 1.6.0 container, as long as you set them with the same value.

Upgrade process

The upgrade of jCustomer based on the jahia/jcustomer Docker image is a straightforward process:

  1. Stop the jCustomer container (or containers if you run a cluster).
  2. Start a new jCustomer container, that points to the same volume and database as the previous one.
  3. For clustered environments, once the first jCustomer container has finished starting, all the others can be started at the same time. The first container to start will upgrade the Elasticsearch data if needed.