Add the GeoIP2/GeoLite2 Database to a Project

Info: This feature requires the GeoLite2 or GeoIP2 database from MaxMind.

Overview

This guide describes how to enable IP geolocation in Bloomreach Content Relevance by adding the MaxMind GeoIP2 or GeoLite2 database to your project.

When to Use

Add the GeoIP2 or GeoLite2 database when you need to resolve visitor IP addresses to geographic information such as longitude, latitude, and city name for use in Relevance targeting.

Download the MaxMind GeoIP2 or GeoLite2 Database

Bloomreach Content supports both the free GeoLite2 database and the commercial GeoIP2 City database from MaxMind. Both databases are compatible with the Relevance Module.

Download either the GeoLite2-City or GeoIP2-City database binary file from MaxMind.

Add the Database to Your Project

You can add the database using one of two methods:

• As a Maven dependency
• As a Spring bean override

Select the method that aligns with your project’s configuration and deployment process.

Method 1: As a Maven Dependency

Wrap the database file in a Maven project and include it as a dependency in your Bloomreach Content implementation project.

Steps

1. Create a Maven project with the following structure:

   brxm-maxmind-geolite2
   |-- src
   |   `-- main
   |       `-- resources
   |           `-- GeoLite2-City.mmdb
   `-- pom.xml
   

2. Place the GeoLite2-City.mmdb file in src/main/resources.

3. Create a root pom.xml file. Adjust the groupId, artifactId, and version as needed for your organization. Use the GeoLite2 release datestamp for the version. Add your organization's Maven repository in the distributionManagement section.

   <?xml version="1.0" encoding="UTF-8"?>
   <project xmlns="http://maven.apache.org/POM/4.0.0"
     xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
     xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 http://maven.apache.org/xsd/maven-4.0.0.xsd">
     <modelVersion>4.0.0</modelVersion>
   
     <groupId>com.mycompany</groupId>
     <artifactId>brxm-maxmind-geolite2</artifactId>
     <version>20200114</version>
   
     <distributionManagement>
       <repository>
         <name>My Company Maven 2 Repository</name>
         <id>maven2-repository</id>
         <url>https://mycompany/maven2/</url>
         <uniqueVersion>false</uniqueVersion>
       </repository>
     </distributionManagement>
   </project>
   copy

   Hint: Build the brxm-maxmind-geolite2 project and deploy the artifact using mvn install (for local use) or mvn deploy (for remote repositories).

4. In your Bloomreach Content implementation project, add the dependency to cms-dependencies/pom.xml:

       <dependency>
         <groupId>com.mycompany</groupId>
         <artifactId>brxm-maxmind-geolite2</artifactId>
         <version>20200114</version>
       </dependency>
   copy

Notes

• If you use the GeoIP2 database, use the filename GeoIP2-City.mmdb instead of GeoLite2-City.mmdb.
• This approach ensures the database is included in your deployment artifacts.

Method 2: As a Spring Bean Override

Override the GeoIPService Spring bean to specify the location of the GeoLite2 or GeoIP2 database file.

Steps

1. Place the GeoLite2-City.mmdb file in a location accessible to your application (for example, /path/to/GeoLite2-City.mmdb).

2. In your implementation project, create a Spring configuration file at cms/src/main/resources/META-INF/hst-assembly/overrides/targeting-addon-geolite2.xml with the following content:

   <?xml version="1.0" encoding="UTF-8"?>
   
   <beans xmlns="http://www.springframework.org/schema/beans"
          xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:util="http://www.springframework.org/schema/util"
          xsi:schemaLocation="http://www.springframework.org/schema/beans http://www.springframework.org/schema/beans/spring-beans-4.1.xsd http://www.springframework.org/schema/util http://www.springframework.org/schema/util/spring-util.xsd">
   
     <bean id="com.onehippo.cms7.targeting.geo.GeoIPService" class="com.onehippo.cms7.targeting.geo.GeoIPServiceImpl">
       <property name="databaseFile" value="/path/to/GeoLite2-City.mmdb" />
     </bean>
   
   </beans>
   copy

3. Update the databaseFile property to the actual path of your GeoLite2 or GeoIP2 database file.

Notes

• Use this method if you prefer to manage the database file outside of your Maven build.
• Ensure the application has read access to the database file at the specified path.

Verification

After adding the database, verify that geolocation targeting in Relevance resolves visitor IP addresses to geographic attributes as expected.

Related Topics

• MaxMind GeoLite2 Documentation
• Relevance Module Configuration