HST Container Configuration

Overview

The HstFilter acts as the front controller for the HST Container. Every incoming request is first processed by the HstFilter. If the request matches criteria for processing by an HST Container Pipeline, the filter delegates the request to the appropriate pipeline. If not, it passes the request to the next filter in the servlet filter chain.

The HstContextLoaderListener initializes all core components of the HST Container when a site application starts.

HstFilter Configuration

In projects created from the archetype, the HstFilter is configured in web.xml as shown below:

<filter>
  <filter-name>HstFilter</filter-name>
  <filter-class>org.hippoecm.hst.container.HstFilter</filter-class>
</filter>

<!-- SNIP -->

<filter-mapping>
  <filter-name>HstFilter</filter-name>
  <url-pattern>/*</url-pattern>
  <dispatcher>REQUEST</dispatcher>
</filter-mapping>
copy

Map the HstFilter to the /* URL pattern. This allows the filter to determine the correct mount for each request and decide whether to process the request using HST pipelines.

Enabling Automatic Content Bean Scanning

To enable automatic scanning for content beans, add the following context-param to your web.xml:

<context-param>
  <param-name>hst-beans-annotated-classes</param-name>
  <param-value>classpath*:org/example/**/*.class
   ,classpath*:org/onehippo/**/*.class
   ,classpath*:com/onehippo/**/*.class
   ,classpath*:org/onehippo/forge/**/*.class
  </param-value>
</context-param>
copy

Replace org.example with your project's groupId if it differs from the example.

For more information, see Automatic Scanning for Content-Bean Annotated Classes.

HstContextLoaderListener Configuration

The HstContextLoaderListener initializes core components for the HST Container, including session pools, event listener containers, site handler components, and the Guava EventBus.

Add the listener to your web.xml as follows:

<listener>
  <listener-class>org.hippoecm.hst.site.container.HstContextLoaderListener</listener-class>
</listener>
copy

You can configure the following servlet context parameters:

Init parameter name	Required?	Example value	Default value	Description
hst-configuration	No	${catalina.base}/conf/hst.xml		Commons-Configuration formatted XML configuration file for the HST Container.
hst-config-properties	No	${catalina.base}/conf/hst-custom.properties	${catalina.base}/conf/hst.properties (SITE application) or ${catalina.base}/conf/platform.properties (CMS/Platform application)	Java standard properties file for the HST Container.
hst-system-properties-override	No	false	true	Determines whether Java System properties override other configuration properties.

Starting with v14.0, if you do not specify the hst-config-properties context parameter, the default configuration file path is either ${catalina.base}/conf/hst.properties (for SITE applications) or ${catalina.base}/conf/platform.properties (for CMS or Platform applications). This separation ensures that configuration properties for CMS/Platform and SITE applications remain isolated, and prevents component code in one application from accessing external service references or credentials intended for another.

Important: Do not supply ${catalina.base}/conf/platform.properties or ${catalina.base}/conf/hst.properties as part of your project distribution. These files should contain environment-specific properties and must be managed outside of the project source. Place non-environment-specific properties in hst-config.properties under /cms/webapp/src/main/webapp/WEB-INF or /site/webapp/src/main/webapp/WEB-INF. Refer to the archetype project setup for details.

Basic HST Container Configuration

When the HST Container initializes, the HstContextLoaderListener locates and reads configuration files to set parameters.

1. Resolving Configuration File Paths

Configuration file paths are resolved as follows:

• If the path starts with /, the file is treated as a web resource within the servlet context. The container attempts to resolve it using javax.servlet.ServletContext#getResource(resourcePath) or getRealPath(resourcePath). If the resource is not found, the path is interpreted as an absolute file path.

• If the path starts with file:, the container loads the file using the file URL.

• If the path does not start with / or file:, it is treated as a path relative to the current working directory.

2. Default Configuration Files

The HST Container combines configuration resources as ordered child Configurations:

1. JVM System properties, unless the hst-system-properties-override context parameter is set to false.

2. An XML file specified by the hst-configuration context parameter, if present.

3. A Java properties file specified by the hst-config-properties context parameter, if present. If not specified, defaults to ${catalina.base}/conf/hst.properties (SITE) or ${catalina.base}/conf/platform.properties (CMS/Platform).

4. /WEB-INF/hst-configuration.xml, if present. Otherwise, /WEB-INF/hst-config.properties, if present.

The container searches for a property in the first configuration, then proceeds to the next if not found, and so on. The order determines precedence. For details, see the CompositeConfiguration Javadoc.

For example, if your environment includes ${catalina.base}/conf/hst.properties and /WEB-INF/hst-config.properties, the container loads and combines:

• Java System properties

• ${catalina.base}/conf/hst.properties

• /WEB-INF/hst-config.properties

Property lookup starts with Java System properties, then proceeds to the next configuration if not found.

This approach allows you to separate configuration sets. For example, developer-specific settings that should not be updated by administrators can reside in /WEB-INF/hst-config.properties, while environment-specific settings can be placed in ${catalina.base}/conf/hst.properties.

Note: Multiple configuration files are combined by default to support property value expansion and to allow separation of configuration sets. For example, you can reference a property like ${brc.appconfigpath} in hst.properties if Java System properties are included first. This structure also enables you to keep environment-agnostic and environment-specific configurations separate.

3. Archetype-Generated Configuration and SpringComponentManager.properties

The archetype-generated /WEB-INF/hst-config.properties is empty by default:

# this file is used to be able to override defaults from
# org/hippoecm/hst/site/container/SpringComponentManager.properties

This file allows you to override defaults from the HST core SpringComponentManager.properties.

Note: In most cases, you can keep all properties in the default configuration files (${catalina.base}/conf/hst.properties or ${catalina.base}/conf/platform.properties). Other files are loaded only if present. Unless you have a specific need, rely on the default configuration files.

Advanced HST Container Configuration

You can configure an XML configuration file using the hst-configuration context parameter:

<context-param>
  <param-name>hst-configuration</param-name>
  <param-value>${catalina.base}/conf/hst.xml</param-value>
</context-param>
copy

To combine additional application-specific configuration files, include them in the XML configuration:

<?xml version="1.0" ?>
<configuration>
  <!-- Includes system properties regardless of hst-system-properties-override context param -->
  <system/>
  <!-- Include extra application specific properties files -->
  <properties fileName='${catalina.base}/conf/custom-app1.properties'/>
  <properties fileName='${catalina.base}/conf/custom-app2.properties'/>
</configuration>
copy

In this example, the XML file acts as a CompositeConfiguration child of the root HST Container configuration. The result is a configuration hierarchy that includes Java System properties, custom-app1.properties, and custom-app2.properties.

If your environment includes ${catalina.base}/conf/hst.xml, ${catalina.base}/conf/hst.properties, and /WEB-INF/hst-config.properties, the container loads and combines:

• Java System properties

• ${catalina.base}/conf/custom-app1.properties

• ${catalina.base}/conf/custom-app2.properties

• ${catalina.base}/conf/hst.properties

• /WEB-INF/hst-config.properties

For more information on Commons-Configuration XML Configuration, see the Commons Configuration User Guide.

Archetype Project Configuration Structure

When you create a new project from the archetype, the conf directory includes files such as:

hst-dev.properties
hst-platform.properties

Developers use these files to configure properties specific to their local development environment, such as test configuration parameters. Files like hst-dev.properties, hst-platform.properties, and log4j2-dev.xml are intended only for local development and are not included in the distribution.

Do not add hst.properties or platform.properties to the /conf directory in your project source. These files are environment-specific and should be managed by DevOps teams. They differ between environments (e.g., test, acceptance, production) and must not be included in the distribution.

Developers can add environment-agnostic properties to:

/cms/webapp/src/main/webapp/WEB-INF/hst-config.properties
/site/webapp/src/main/webapp/WEB-INF/hst-config.properties

These files are included in the project distribution.

Environment-Specific Configuration on Bloomreach Cloud

On Bloomreach Cloud, you can set environment-specific configuration files. This mechanism allows you to deploy different HST configuration files, such as platform.properties, to different environments. Refer to the linked Bloomreach Cloud documentation for a complete guide.