Multi Site Web Application Mode - BloomReach Experience - Open Source CMS
06-12-2019

Multi Site Web Application Mode

Setting up multiple site web applications within the same project is intended to enable separate development teams working independently on their respective sites. Bloomreach recommends setting up multiple site web applications only in this specific development scenario.

As of Bloomreach Experience Manager version 13, Multi Site Mode refers to the default structure of Bloomreach Experience Manager projects, as produced by the archetypes, which supports developing and maintaining multiple site web applications in the context of a single Bloomreach Experience Manager project (consisting of potentially multiple sub-projects).

Two Archetypes

As of version 13, there are two Bloomreach Experience Manager archetypes for scaffolding new Bloomreach Experience Manager sub-projects, the archetype for the parent sub-project and the archetype for a site sub-project. A Multi Site Mode Bloomreach Experience Manager project consists of one parent sub-project and zero or more site sub-projects.

Parent Sub-Project Structure

A parent sub-project is produced from the archetype org.onehippo.cms7:hippo-project-archetype. In terms of Maven modules, the structure of a base project looks like this:

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

The purpose of each module is as follows:

  • cms produces the CMS/platform web application, to be shared across all site web applications of this Bloomreach Experience Manager project. (WAR) It depends on the cms-dependencies POM artifact.
  • cms-dependencies collects all dependencies of the CMS/platform web application using POM packaging in order to facilitate the building of the CMS/platform web application in the context of site sub-projects. It includes the dependency on the repository-data/application artifact.
  • essentials produces the Essentials web application for local development. (WAR)
  • repository-data logically groups all artifacts containing repository data.
  • repository-data/application contains repository data definitions pertaining to the CMS/platform web application and essential to each runtime environment, including production systems. (JAR)
  • repository-data/development contains repository data definitions pertaining to the CMS/platform web application used only for development and testing purposes. These definitions usually don't end up on production systems. (JAR)
  • repository-data/site contains repository data definitions pertaining to the site web application, which primarily represent HST configuration. This JAR is packaged with the site web application.
  • repository-data/site-development contains repository data definitions pertaining to the site web application used only for development and testing purposes. These definitions usually don't end up on production systems. Note: This module was added in version 13.1.0, so a project created with the 13.0.0 archetype or previous may need to be upgraded to include it. (JAR)
  • repository-data/webfiles contains the webfiles pertaining to the site web application. This JAR, too, is packaged with the site web application.
  • site/components contains all site-specific code (HST components, beans etc.), as well as the site web application's external dependencies (on HST and 3rd party libraries). This JAR is separate from the site web application module, such that the webfiles module can depend on it to trigger IDE auto-completion support without introducing a circular dependency.
  • site/webapp produces the site web application (WAR). It depends on the site/components, repository-data/webfiles and repository-data/site artifacts.

Site Sub-Project Structure

A site sub-project is produced from the archetype org.onehippo.cms7:hippo-site-project-archetype. When producing such a project, you have to link it to its parent sub-project by specifying appropriate values for the following parameters:

  • parentGroupId the Maven group ID of the parent sub-project

  • parentArtifactId the Maven artifact ID of the parent sub-project

  • parentVersion the version of the parent sub-project

In terms of Maven modules, the structure of a site sub-project is the same as the structure of the parent sub-project (see above), however, certain modules have a conceptually different purpose:

  • cms (re-)produces the parent's CMS/platform web application, potentially augmented with extra extensions (coded inside this module), dependencies (specified in the cms-dependencies module) or repository data (defined in the repository-data/application and repository-data/development modules) pertaining to CMS/platform features being developed in the context of this site web application. Such extras are meant for the feature development phase only. When the development of a CMS/platform feature has completed, its extras must be pushed upstream, into the parent sub-project, such that they are available to be pushed into production. After that push, these extras are no longer needed in the site sub-project, and they must be cleaned up. In a stable site 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, as well as the site sub-project's repository-data/application artifact, and includes any temporary dependencies needed for adding CMS/platform features, to be pushed into the parent when development of a feature is done.
  • repository-data/application contains temporary repository data definitions for CMS/platform features under development. When that development has completed, the corresponding definitions need to be pushed upstream, into the parent sub-project's repository-data/application module.
  • repository-data/development and repository-data/site-development contain repository data definitions for the development and testing of features. If these definitions are only interesting to the local site sub-project, they may stay in those modules forever. If they are interesting to all sub-projects of this Bloomreach Experience Manager project, they would typically be pushed to the parent sub-project upon completion of the development of the feature, and be cleaned up in the site sub-project.

The other Maven modules of a site sub-project serve the same purpose as described for the parent sub-project (above).

Site-Specific Repository Data

Multi Site Mode packages site-specific repository data definitions with the site web application. Specifically, the site web application specifies dependencies on the JAR artifacts containing the site's HST configuration (repository-data/site) and the site's web files (repository-data/webfiles), such that these artifacts get packaged inside the site WAR. In order for these definitions to be bootstrapped into the repository, Bloomreach Experience Manager's Configuration Management mechanism has been extended to discover the deployment of a site web application and process the packaged repository data definitions. A new file, hcm-site.yaml controls this mechanism, it is described below.

Multiple HST Root Nodes

In order to keep the HST configuration of a site web application separate from the HST configuration of all other site web applications, each site web application requests its HST configuration to be bootstrapped onto a dedicated repository root node. The site web application must declare which root node to use in the file src/main/webapp/META-INF/hcm-site.yaml. By default, the content of this file in a site sub-project is:

name: mysiteproject
hstRoot: /hst:mysiteproject

The hstRoot property specifies that the HST configuration of this site web application is rooted at node /hst:mysiteproject.

Make sure that the value of the hstRoot property matches the value of the hst.configuration.rootPath property of the hst-config.properties.

The Configuration Management mechanism scans for the hcm-site.yaml file in a site web application, and, when detected, bootstraps the repository data definitions found in that site web application into the repository.

Your site web application's repository data definition YAML files do not need to specify the root node name for HST configuration exactly like specified in hcm-site.yaml. As an alternative, if the YAML files use the name /hst:hst (as in the example below), /hst:hst will be replaced by the value specified in hcm-site.yaml (i.e. /hst:mysiteproject) during bootstrapping. This mechanism allows for easier sharing or moving of HST configuration YAML files.

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

Even though the definition uses /hst:hst, the prod virtual host group node will be bootstrapped below /hst:mysiteproject.

Your site web application must declare a dependency on org.onehippo.cms7.hst.toolkit-resources.addon:hst-addon-hcm-site, which uses this mechanism to ensure that the basic structure of the HST configuration is bootstrapped below the designated root node.

Multiple Webfile Bundles

In order to keep the web files of each site web application separate, each site web application must define its own web file bundle. The name of the web file bundle is determined through the corresponding definition in the web files artifact, typically src/main/resources/hcm-config/main.yaml:

definitions:
  webfilebundle: mysiteproject
Did you find this page helpful?
How could this documentation serve you better?
On this page
    Did you find this page helpful?
    How could this documentation serve you better?