Configuring jCustomer

jCustomer core functionalities and data model are based upon Apache Unomi. We recommend reviewing Apache Unomi's documentation for additional details and configuration examples.

Environment variables

jCustomer is configured by means of environment variables, all of which are listed and documented in Unomi’s custom.system.properties file.

If you want to change the default configuration, you can perform any modification you want in the <jcustomer-install-dir>/etc directory by creating your own custom configuration in the unomi.custom.system.properties configuration file. You can find default values for the properties in the custom.system.properties file.

For example, you defines the addresses and ports where jCustomer can be found:


org.apache.unomi.cluster.group=${env:UNOMI_CLUSTER_GROUP:-default}
# To simplify testing we set the public address to use HTTP, but for production environments it is highly recommended
# to switch to using HTTPS with a proper SSL certificate installed.
org.apache.unomi.cluster.public.address=${env:UNOMI_CLUSTER_PUBLIC_ADDRESS:-http://localhost:8181}
org.apache.unomi.cluster.internal.address=${env:UNOMI_CLUSTER_INTERNAL_ADDRESS:-https://localhost:9443}

jCustomer specific environment variables

In addition to Unomi environment variables, a few jCustomer-specific variables are available and are mostly applicable to the context of Docker.

These variables are detailed in the “Using jCustomer docker image” page.

Installing the MaxMind GeoIPLite2 IP lookup database

jCustomer requires an IP database to resolve IP addresses to user location.
When installing jCustomer manually, the GeoLite2 database can to be downloaded from the Maxmind website, where you'll need to create an account: https://dev.maxmind.com/geoip/geolite2-free-geolocation-data?lang=en

Once your account is created, you can find the GeoLite2 city file under "GeoIP2 / GeoLite2" => "Download files". Then download the gzip file GeoLite2-City_<date_of_download>.tar.gz and unzip it to get the file GeoLite2-City.mmdb .

Once the file is unzipped, copy it into the <jcustomer-install-dir>/etc directory.

If using jCustomer in Docker, a dedicated environment variable is available to directly provide jCustomer with the URL of a .tar.gz file containing the Geo IP mmdb file.

Installing Geonames database

jCustomer includes a geocoding service based on the geonames database (http://www.geonames.org/). You can use it to create conditions based on countries or cities.

When installing jCustomer manually, the Geonames database can be downloaded at the following location: http://download.geonames.org/export/dump/

Download it and put the allCountries.zip file in the <jcustomer-install-dir>/etc directory, without unzipping it. Then, edit the <jcustomer-install-dir>/etc/unomi.custom.system.properties file and set the org.apache.unomi.geonames.forceImport property to true. The data import should start right away. Otherwise, the import should start at the next startup. The 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.

If using jCustomer in Docker, a dedicated environment variable is available to directly provide jCustomer with the URL of an allCountries.zip file.