Run Two Local Bloomreach Content Instances Simultaneously

Overview

This guide explains how to run two Cargo-based Bloomreach Content instances at the same time in a development environment.

When to Use

Run multiple local XM instances when you need to:

Develop or debug features in parallel
Test integrations between separate XM projects
Compare configurations or customizations

Default Port Usage

A default XM archetype project uses the following ports:

8080: Tomcat HTTP connector (site and CMS)
8205: Tomcat shutdown command port
8009: Tomcat AJP connector (secure connections)
8000: Java debug port

Additional ports may be in use:

1099: RMI (if enabled; RMI is deprecated as of version 17.0.0)
9200, 9300: Elasticsearch (if Relevance is enabled)

To run two instances simultaneously, you must assign alternative port numbers to one of the instances to avoid conflicts.

Note: RMI and its parameters (repository-address and start-remote-server) are not supported as of version 17.0.0.

Prerequisites

Two separate Bloomreach Content projects
Maven installed
Sufficient system resources to run two Tomcat instances

Configuration Steps

1. Update Ports in the Second Project

In the second project's root pom.xml, update the cargo-maven3-plugin configuration to use alternative ports. Edit the Cargo profile as shown below:

<plugin>
   <groupId>org.codehaus.cargo</groupId>
   <artifactId>cargo-maven3-plugin</artifactId>
   <configuration>
     <configuration>
       <properties>
         <cargo.servlet.port>9080</cargo.servlet.port>
         <cargo.tomcat.ajp.port>9009</cargo.tomcat.ajp.port>
         <cargo.rmi.port>9205</cargo.rmi.port>
         <cargo.jvmargs>
           <![CDATA[-agentlib:jdwp=transport=dt_socket,address=9000,server=y,suspend=n -noverify ${javaagent}]]>
         </cargo.jvmargs>
       </properties>
       <!-- Additional configuration -->
     </configuration>
   </configuration>
</plugin>

Important: Ensure there is only one <properties> tag at this level. Some pom.xml files may already include a <properties> section.

2. Update Elasticsearch Ports (If Using Relevance)

If your project uses Relevance, also update the Elasticsearch ports:

In the root pom.xml, within the cargo.run profile, set alternative port numbers for Elasticsearch:

<profile>
  <id>cargo.run</id>
  <!-- SNIP -->
  <properties>
    <es.tcpPort>9500</es.tcpPort>
    <!-- SNIP -->
    <es.httpPort>9400</es.httpPort>
    <!-- SNIP -->
  </properties>
</profile>

In conf/context.xml, update the Elasticsearch data store configuration to match the new es.httpPort value:

<Environment name="elasticsearch/targetingDS" value="{'indexName':'visits', 'locations':['http://localhost:9400/']}" type="java.lang.String"/>

3. Start the Second Instance

Start the second instance using the Cargo profile:

mvn -P cargo.run

4. Use Distinct Hostnames

Assign a different hostname for each Tomcat instance to prevent HTTP session conflicts. For example:

Instance 1: http://localhost:8080/cms
Instance 2: http://127.0.0.1:9080/cms

If both instances use the same hostname, session data may be shared, causing user session conflicts.

5. (Optional) Update Repository Address for JCR Runner

Some use cases, such as using the JCR runner, require separate repository addresses. Update the repository-address context parameter in the CMS web descriptor or in conf/context.xml as needed.

6. Update Experience Manager Host Configuration

If you run the Experience Manager on a port other than the default (8080), update the host configuration:

In the CMS Console, set the port to match the value defined in your pom.xml. For example, at /hst:myproject/hst:hosts/dev-localhost:
```
- hst:defaultport = 9080
```
Rename the node /hst:myproject/hst:hosts/dev-localhost/localhost to /hst:myproject/hst:hosts/dev-localhost/127.0.0.1.
Rename the node /hst:platform/hst:hosts/dev-localhost/localhost to /hst:platform/hst:hosts/dev-localhost/127.0.0.1.

For more details, see View a document in a channel.

Verification

Access each CMS instance using its assigned hostname and port.
Confirm that each instance operates independently and that user sessions do not conflict.
If using Relevance, verify that Elasticsearch is accessible on the configured ports.

Troubleshooting

If you encounter port conflicts, verify that all relevant ports are unique for each instance.
If session data is shared between instances, confirm that each instance uses a distinct hostname.
For issues with Relevance or Elasticsearch, ensure that the port numbers in both the pom.xml and context.xml match.

View a document in a channel