Configure Bloomreach Experience Manager for Your Database Server

Overview

This guide describes how to configure Bloomreach Experience Manager (XM) to use a supported external database server instead of the default H2 database.

When to Use

Use this configuration when deploying Bloomreach Experience Manager to any environment other than local development, such as test, acceptance, or production. The default H2 database is only supported for local development.

Prerequisites

You have completed the Linux Installation Manual or have a similar environment.
Apache Tomcat is used as the application container.
The target database server is installed, running, and accessible.
The database is listed as supported by Bloomreach Experience Manager.

Implementation Steps

To connect Bloomreach Experience Manager to an external database, you must configure both the application container and the content repository.

1. Configure the Container JNDI Datasource

Configure your application container to expose the database connection as a JNDI resource. The following example uses Apache Tomcat.

Refer to your container's documentation for details on how to define a JNDI datasource.

2. Configure the Content Repository

The content repository is the only component that connects directly to the database. Both the CMS UI and the delivery tier (HST) interact with the content repository, not the database.

Specify the Location of `repository.xml`

The content repository configuration is defined in the repository.xml file. By default, this file is located at org/hippoecm/repository/repository.xml on the classpath and is configured for H2. For external environments, provide an environment-specific repository.xml file outside the application.

You can specify the location of repository.xml in one of two ways:

System property:

-Drepo.config=file:///path/to/repository.xml

Context parameter (Apache Tomcat example):

<Parameter name="repository-config" value="file:///path/to/repository.xml" override="false"/>

Update Database-Specific Settings in `repository.xml`

Edit repository.xml to match your target database. The following elements must be configured with database-specific values:

databaseType
FileSystem class
PersistenceManager class
Journal class
DataStore class
tableSpace (optional; only for certain databases)

Refer to the relevant database-specific documentation for the required values.

Verification

After configuring the datasource and updating repository.xml, start Bloomreach Experience Manager and verify that it connects to the external database without errors.

Troubleshooting

If the application fails to start, review the logs for database connection errors.
Ensure the JNDI datasource name matches between the container configuration and repository.xml.
Confirm that the database user has the necessary permissions.

Database-Specific Configuration Guides

Refer to the following pages for detailed configuration instructions for each supported database: