Using jCustomer docker image

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:

Stop the jCustomer container (or containers if you run a cluster).
Start a new jCustomer container, that points to the same volume and database as the previous one.
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.