Bloomreach Content Load Balancing Requirements

Overview

This page describes the load balancing requirements for running Bloomreach Content behind a load balancer, including server affinity strategies and configuration details for both traditional and headless (SPA) integrations.

When to Use

Configure server affinity when deploying Bloomreach Content behind a load balancer. Server affinity ensures that both the CMS and Site web applications are accessed through the same backend application server for each client session.

Prerequisites

You are deploying Bloomreach Content with both CMS and Site applications on the same application server (for example, Tomcat).
You are using a load balancer in front of your application servers.

Server Affinity Strategies

Bloomreach Content supports two server affinity strategies for load balancers:

Source IP Affinity

With source IP affinity, the load balancer routes all requests from a specific client IP address to the same backend server.

Considerations:

This approach can lead to uneven traffic distribution if multiple users share a single external IP address (for example, users behind a corporate NAT).
This strategy is not compatible with headless integration scenarios. In these cases, all Delivery API requests originate from the frontend application's IP address, which prevents proper session routing.

With this strategy, the load balancer injects a dedicated cookie (such as SERVERID) to maintain server affinity. The load balancer uses this cookie to consistently route requests from the same client to the same backend server.

Use a separate affinity cookie. Do not reuse application session cookies.
This is the recommended strategy for all deployment scenarios.
This strategy is required for headless integrations. See Additional Requirements for Frontend Applications in Headless Integrations.

Example: HAProxy Backend Configuration

The following HAProxy configuration injects a SERVERID cookie to track server affinity:

backend brxm 
  balance roundrobin
  cookie SERVERID insert nocache httponly maxidle 1h
  server node1 10.10.10.1:8080 check cookie node1
  server node2 10.10.10.2:8080 check cookie node2

Note:
This configuration is an example only. Configuration details vary between load balancer products. Complete load balancer configuration is outside the scope of Bloomreach support.

Set the SERVERID cookie path to /. After logging in to the CMS, you should see a cookie similar to the following:

Name	Value	Domain	Path
SERVERID	16cad8c0e739011127f5b12db02ce241763079f2	cms.my.domain	/

If the cookie path is set to a subpath (for example, /cms), the Experience manager app will not function correctly. This typically results in HTTP 409 errors for some requests. For troubleshooting steps, see Channel Manager Troubleshooting.

Additional Requirements for Frontend Applications in Headless Integrations

When using the Delivery API for preview data in a headless integration, server affinity is required only for preview mode. Do not use this requirement in live mode.

The Delivery API uses JSON Web Token (JWT) authentication.
In addition to the SERVERID cookie, you must pass a Server-Id header in outgoing Delivery API requests.
The value for the Server-Id header is provided as a server-id query string parameter. This parameter is appended to the preview URL configured for a channel in the org.hippoecm.hst.configuration.channel.PreviewURLChannelInfo_url parameter. For configuration details, see Configure HST for SPA SDK.

The SPA SDK automatically handles the server-id query parameter. No additional configuration is required for standard SPA SDK integrations.

The load balancer must consider both the SERVERID cookie and the Server-Id header when routing requests. Below is an example HAProxy backend configuration:

backend brxm 
  balance roundrobin
  cookie SERVERID insert nocache httponly maxidle 1h
  use-server node1 if { req.hdr(Server-Id) -i node1 }
  server node1 10.10.10.1:8080 check cookie node1
    use-server node2 if { req.hdr(Server-Id) -i node2 }
  server node2 10.10.10.2:8080 check cookie node2