Add the Lucene Index Export Service to a Project

Introduction

Goal

Add a Lucene Index Export REST service which enables administrators to export a Lucene index on-the-fly from a running production instance.

Background

When moving a Bloomreach Experience Manager instance from one environment to another, it may be desirable to move its Lucene index along with it to prevent the need for (time-consuming) reindexing. However, to backup a Lucene index folder normally requires that the application is not running. The optional Lucene Index Export add-on adds a Repository JAX-RS service which enables on-the-fly export of the Lucene index from a running production instance.

This page describes how to add the Lucene Index Export service to a Bloomreach Experience Manager implementation project.

For instructions on using the Lucene Index Export service see Export the Lucene Index from a Running Production Environment.

To understand how the Lucene Index Export service works, see Lucene Export Explained.

Installation through Essentials

As of Bloomreach Experience Manager v12.1, the Lucene Index Export add-on can be installed into your project through Essentials (v4.1). If you start developing a new project, ensure that you "Make use of Enterprise features", navigate to the Library tab in Essentials, locate the Lucene Index Exporter feature and click "Install feature". Essentials then applies the steps documented for manual installation below to your project. Rebuild and restart your project, and verify the service URL as described below.

Manual Installation Instructions

In cms-dependencies/pom.xml of your enterprise project, add:

<dependency>
  <groupId>com.onehippo.cms7</groupId>
  <artifactId>hippo-addon-lucene-export</artifactId>
</dependency>

Verify Servlet and Servlet Mapping

Make sure that cms/src/main/webapp/WEB-INF/web.xml contains the following servlet and servlet mapping (projects created from a recent archetype have these by default), and if not, add them:

<servlet>
  <servlet-name>RepositoryJaxrsServlet</servlet-name>
  <servlet-class>org.onehippo.repository.jaxrs.RepositoryJaxrsServlet</servlet-class>
  <load-on-startup>6</load-on-startup>
</servlet>

<servlet-mapping>
  <servlet-name>RepositoryJaxrsServlet</servlet-name>
  <url-pattern>/ws/*</url-pattern>
</servlet-mapping>

Verify Service URL

After creating and deploying a distribution with the above added dependencies, the Lucene Export service will be available at the following URL:

https://{hostname}/cms/ws/indexexport

(where {hostname} is the host name of the environment)

Secured access

Access to the Lucene Index export endpoint is by default protected with basic authentication. The Add-on defines a new role "indexexport" and a new domain "indexexport", which assigns the "index:export" privilege on the add-on's module configuration node to all members of the "admin" group. (See here for more info about roles, domains and privileges) You can adjust that domain to your project's specific needs.

Above authentication mechanism is enabled by default. If your project is only hosted in an already sufficiently secured and trusted environment, you can disable the authentication mechanism by setting the index.export.secure.disable environment variable to true.