Bloomreach IP Filter – Installation of the IP Filter plugin

Installation of the IP Filter plugin

These instructions assume a Bloomreach Experience project based on the website archetype, i.e. a Maven multi-module project with parent pom org.onehippo.cms7:hippo-cms7-release and consisting of at least three sub-modules: cms, site and repository-data.

Forge Repository

In the main pom.xml of the project, in the repositories section, add this repository if it is not configured there yet.

<repository>
  <id>bloomreach-forge</id>
  <name>Bloomreach Forge Maven 2 repository.</name>
  <url>https://maven.bloomreach.com/repository/maven2-forge/</url>
  <snapshots>
    <enabled>false</enabled>
  </snapshots>
  <releases>
    <updatePolicy>never</updatePolicy>
  </releases>
  <layout>default</layout>
</repository>

Dependency management

Add this property to the properties section of the root pom.xml:

<bloomreach.forge.ipfilter.version>version.number</bloomreach.forge.ipfilter.version>

Select the correct version for your project. See the release notes for more information on which version is applicable.

Add these dependencies to the <dependencyManagement> section of the root pom.xml:

  <dependency>
    <groupId>org.bloomreach.forge.ipfilter</groupId>
    <artifactId>bloomreach-ipfilter-hst</artifactId>
    <version>${bloomreach.forge.ipfilter.version}</version>
  </dependency>
  <dependency>
    <groupId>org.bloomreach.forge.ipfilter</groupId>
    <artifactId>bloomreach-ipfilter-cms</artifactId>
    <version>${bloomreach.forge.ipfilter.version}</version>
  </dependency>

Note: before version 3.0, the artifacts' groupId was org.onehippo.forge.ipfilter and the artifactIds started with hippo-ipfilter

Installation in site application

Add this dependency to the <dependencies> section of the site/pom.xml. It contains the site IP filter.

  <dependency>
    <groupId>org.bloomreach.forge.ipfilter</groupId>
    <artifactId>bloomreach-ipfilter-hst</artifactId>
  </dependency>

Add the following filter to the site’s web.xml. It should be defined as second filter mapping in chain so just after CharacterEncodingFilter (in a standard Hippo project).

  <filter>
    <filter-name>HippoIpFilter</filter-name>
    <filter-class>org.onehippo.forge.ipfilter.hst.IpFilter</filter-class>
  </filter>

  <!-- second mapping! -->
  <filter-mapping>
    <filter-name>HippoIpFilter</filter-name>
    <url-pattern>/*</url-pattern>
  </filter-mapping>

Installation in CMS application

Always add the following dependency to the <dependencies> section of the cms/pom.xml. It contains default configuration and the CMS filter.

  <dependency>
    <groupId>org.bloomreach.forge.ipfilter</groupId>
    <artifactId>bloomreach-ipfilter-cms</artifactId>
  </dependency>

Optionally, install the CMS filter. The CMS is password protected already but if the IP filtering functionality is also required for the CMS, add the following filter to the CMS’s web.xml. It should be defined as first filter in chain.

  <filter>
    <filter-name>HippoCmsIpFilter</filter-name>
    <filter-class>org.onehippo.forge.ipfilter.cms.CmsIpFilter</filter-class>
  </filter>

  <!-- first mapping! -->
  <filter-mapping>
    <filter-name>HippoCmsIpFilter</filter-name>
    <url-pattern>/*</url-pattern>
  </filter-mapping>

Bootstrapping

When running a version 12 or later, make sure your project bootstraps after bloomreach-forge group. Typically, add it in file repository-data/application/src/main/resources/hcm-module.yaml:

  group:
    name: <your-group-name>
    after: [hippo-cms, bloomreach-forge]

Rebuild your project and distribute. In case you start with an existing repository don’t forget to add -Drepo.bootstrap=true to your startup options.