Multi Delivery Web Application Mode

Info: Configure multiple delivery web applications within a single project only when separate development teams need to work independently on their own delivery web applications. In most scenarios, use multiple channels within a single delivery web application.

Starting with brXM version 13, Multi Delivery Webapp Mode refers to the default project structure generated by the archetypes. This structure supports developing and maintaining multiple delivery web applications within a single Bloomreach Content project, which may include several sub-projects.

Two Archetypes

From version 13 onward, Bloomreach Content provides two archetypes for creating new sub-projects:

The parent sub-project archetype
The delivery webapp sub-project archetype

A Multi Delivery Webapp Mode project contains one parent sub-project and zero or more delivery webapp sub-projects.

Parent Sub-Project Structure

The parent sub-project is generated using the org.onehippo.cms7:hippo-project-archetype. The base project structure includes the following Maven modules:

/cms
/cms-dependencies
/essentials
/repository-data
  /application
  /development
  /site
  /site-development
  /webfiles
/site
  /components
  /webapp

Module purposes:

cms: Builds the CMS/platform web application (WAR) shared by all delivery web applications in the project. Depends on cms-dependencies.
cms-dependencies: Aggregates all dependencies for the CMS/platform web application using POM packaging. Facilitates building the CMS/platform web application within delivery webapp sub-projects. Depends on repository-data/application.
essentials: Builds the Essentials web application for local development (WAR).
repository-data: Groups artifacts containing repository data.
repository-data/application: Contains repository data definitions for the CMS/platform web application required in all runtime environments, including production (JAR).
repository-data/development: Contains repository data definitions for the CMS/platform web application used only for development and testing. These definitions are not intended for production (JAR).
repository-data/site: Contains repository data definitions for the delivery web application, primarily HST configuration. Packaged with the delivery web application.
repository-data/site-development: Contains repository data definitions for the delivery web application used only for development and testing. Not intended for production. Note: This module is available from version 13.1.0. Projects created with version 13.0.0 or earlier may require an upgrade to include it (JAR).
repository-data/webfiles: Contains web files for the delivery web application. Packaged with the delivery web application (JAR).
site/components: Contains delivery webapp-specific code (HST components, beans, etc.) and external dependencies. Kept separate from the delivery web application module to allow the webfiles module to depend on it for IDE auto-completion, avoiding circular dependencies.
site/webapp: Builds the delivery web application (WAR). Depends on site/components, repository-data/webfiles, and repository-data/site.

Delivery Webapp Sub-Project Structure

The delivery webapp sub-project is generated using the org.onehippo.cms7:hippo-site-project-archetype. When generating this sub-project, link it to the parent sub-project by specifying:

parentGroupId: Maven group ID of the parent sub-project
parentArtifactId: Maven artifact ID of the parent sub-project
parentVersion: Version of the parent sub-project

The Maven module structure of a delivery webapp sub-project matches the parent sub-project, but some modules serve different purposes:

cms: Rebuilds the parent CMS/platform web application, possibly with additional extensions, dependencies, or repository data specific to features under development in this delivery web application. These additions are temporary and should be moved to the parent sub-project when feature development is complete. After merging, remove these extras from the delivery webapp sub-project. In a stable delivery webapp sub-project, the cms, cms-dependencies, and repository-data/application modules should be empty.
cms-dependencies: Depends on the parent sub-project's cms-dependencies artifact and the delivery webapp sub-project's repository-data/application artifact. Includes temporary dependencies for CMS/platform features under development, to be moved to the parent when complete.
repository-data/application: Contains temporary repository data definitions for CMS/platform features under development. Move these definitions to the parent sub-project's repository-data/application module when development is complete.
repository-data/development and repository-data/site-development: Contain repository data definitions for developing and testing features. If these definitions are only relevant to the local delivery webapp sub-project, they can remain. If they are relevant to all sub-projects, move them to the parent sub-project after development and remove them from the delivery webapp sub-project.

All other modules in the delivery webapp sub-project have the same purpose as in the parent sub-project.

Delivery Webapp-Specific Repository Data

In Multi Webapp Mode, delivery webapp-specific repository data definitions are packaged with the delivery web application. The delivery web application declares dependencies on the JAR artifacts containing its HST configuration (repository-data/site) and web files (repository-data/webfiles). These artifacts are included in the delivery webapp WAR.

Bloomreach Content's Configuration Management mechanism has been extended to detect delivery web application deployments and process the packaged repository data definitions. The hcm-site.yaml file controls this process.

Multiple HST Root Nodes

To isolate the HST configuration of each delivery web application, each application bootstraps its HST configuration onto a dedicated repository root node. Specify the root node in src/main/webapp/META-INF/hcm-site.yaml. By default, this file contains:

name: mysiteproject
hstRoot: /hst:mysiteproject

The hstRoot property sets the root node for the delivery web application's HST configuration (e.g., /hst:mysiteproject).

Ensure that the hstRoot value matches the hst.configuration.rootPath property in hst-config.properties.

The Configuration Management mechanism scans for hcm-site.yaml in the delivery web application. When found, it bootstraps the repository data definitions from the delivery web application into the repository.

You do not need to specify the exact root node name in your delivery web application's repository data definition YAML files. If your YAML files use /hst:hst as the root, the system replaces /hst:hst with the value from hcm-site.yaml (e.g., /hst:mysiteproject) during bootstrapping. This approach allows you to share or move HST configuration YAML files more easily.

definitions:
  config:
    /hst:hst/hst:hosts/prod:
      jcr:primaryType: hst:virtualhostgroup
      # SNIP

In this example, the prod virtual host group node is bootstrapped under /hst:mysiteproject.

Declare a dependency on org.onehippo.cms7.hst.toolkit-resources.addon:hst-addon-hcm-site in your delivery web application. This dependency ensures the basic HST configuration structure is bootstrapped under the specified root node.

Multiple Webfile Bundles

To keep web files for each delivery web application separate, define a unique web file bundle for each application. Set the bundle name in the web files artifact, typically in src/main/resources/hcm-config/main.yaml:

definitions:
  webfilebundle: mysiteproject