Convert from Single to Multi Delivery Webapp Mode

As part of the instructions for upgrading a Bloomreach Experience Manager project to version 13, you have put your project into Single Delivery Webapp Mode. If you would like to benefit from Multi Delivery Webapp Mode (i.e. add another delivery web application to your project, or just bring your project in line with the version 13 default project structure, used throught our documentation), this page describes how to convert your Single Delivery Webapp Mode project into a Multi Delivery Webapp Mode project.

Instructions

1 - Remove hcm.properties file

Remove the file cms/src/main/resources/hcm.properties, it is no longer used.

2 - Split up repository data application and development artifacts

All HST configuration defined in the repository-data/application module must be extracted into a separate, new module repository-data/site. To that new module, add the file src/main/resources/hcm-module.yaml and fill it with the following content, matching the group and project names to your specific project:

group:
  name: myproject
  after: hippo-cms
project: myproject
module: myproject-repository-data-site

Normally, each YAML source in the repository-data/application module defines either HST configuration or not. Move the YAML sources with HST configuration below src/main/resources/hcm-config or src/main/resources/hcm-content to the new repository-data/site module. Be careful to preserve the VCS history of the moved files. If you find YAML sources which contain both definitions for HST configuration and definitions for other nodes, these sources must be split, such that only the HST configuration is moved into the repository-data/site module. Make sure the repository-data/site module is linked into your Maven project, such that it gets built along with the other modules.

Similarly, move YAML source files from the repository-data/development module that contain HST configuration into a new repository-data/site-development module. Create the file src/main/resources/hcm-module.yaml and fill it with the following content, adjusted to your project.

site: myproject
group: myproject
project: myproject
module: 
  name: myproject-repository-data-site-development
  after: myproject-repository-data-site

Open your project's pom.xml, locate the cargo.run Maven profile and add the following <file> element under <files> element:

<file>
  <file>${project.basedir}/repository-data/site-development/target/${artifactId}-repository-data-site-development-${project.version}.jar</file>
  <todir>${development-module-deploy-dir}</todir>
</file>

Add an additional assembly file element at src/main/assembly/shared-lib-development-data.xml:

<file>
  <source>repository-data/site-development/target/${artifactId}-repository-data-site-development-${project.version}.jar</source>
  <outputDirectory>shared/lib</outputDirectory>
</file>

3 - Split up site module into components and web application

In your project's site module (i.e. the module producing the site WAR), add two new Maven (sub-)modules: site/components and site/webapp. Move all Java code (src/main/java/...) from the site module into the site/components module. Also, move all resources (src/main/resources/...) related to the moved Java code from the site module to the site/components module. Make sure to move test classes and resources accordingly. And, move all dependencies on project-external artifacts from the site module into the site/components module. Move all remaining resources of the former site module, i.e. resources specific to the site web application, into the site/webapp module. Make sure that the site/webapp module uses WAR packaging and specifies a dependency on the artifact produced by the site/components artifact, for example:

<dependency>
  <artifactId>myproject-components</artifactId>
  <groupId>${project.groupId}</groupId> 
  <version>${project.version}</version>
</dependency>

Change the now "empty" site module to use POM packaging, and make sure that the new sub-modules are correctly linked into the project's module structure.

4 - Add/move the delivery webapp-specific repository data definitions to the delivery web application

Add a dependency to the new repository-data/site artifact to the site/webapp module. Move the dependencies on the repository-data/webfiles and on org.onehippo.cms7.hst.toolkit-resources.addon:hst-addon-hcm-site from the CMS/platform web application into the site/webapp module. The list of dependencies of the site/webapp module should now look like this:

<dependency>
  <artifactId>myproject-repository-data-site</artifactId>
  <groupId>${project.groupId}</groupId> 
  <version>${project.version}</version>
</dependency>
<dependency>
  <artifactId>myproject-repository-data-webfiles</artifactId>
  <groupId>${project.groupId}</groupId> 
  <version>${project.version}</version>
</dependency>
<dependency>
  <artifactId>myproject-components</artifactId>
  <groupId>${project.groupId}</groupId> 
  <version>${project.version}</version>
</dependency>
<dependency>
  <groupId>org.onehippo.cms7.hst.toolkit-resources.addon</groupId>
  <artifactId>hst-addon-hcm-site</artifactId>
</dependency>

On top of above dependencies, scan the dependencies of the cms module to find dependencies on artifacts that relate to delivery webapp-specific repository data. Such artifacts often have the terms "site" and "hcm" in their names. Move them from the cms module into the site/webapp module as well, so they get packaged with the delivery web application. When in doubt, consult the installation instructions for the plugin/add-on to which the artifact pertains.

5 - Change the webfiles module to depend on the site/components artifact

The repository-data/webfiles module defines a dependency on the site artifact. Change that dependency to point to the site/components artifact instead:

<dependency>
  <artifactId>myproject-components</artifactId>
  <groupId>${project.groupId}</groupId> 
  <version>${project.version}</version>
  <scope>provided</scope>
</dependency>

6 - Tell HCM where to bootstrap your HST configuration to

Create a new file site/webapp/src/main/webapp/META-INF/hcm-site.yaml and fill it with the following content. This will tell HCM where to bootstrap your HST configuration to.

name: myproject
hstRoot: /hst:hst

7 - Tell HST where to load your HST configuration from

In site/webapp/src/main/webapp/WEB-INF/hst-config.properties, make sure the hst.configuration.rootPath property is specified with the same value you just put into the hcm-site.yaml file:

hst.configuration.rootPath = /hst:hst

8 - Split out the CMS/platform dependencies

Create a new root-level Maven module cms-dependencies with POM packaging. Move all dependencies from the cms module into the cms-dependencies module, and add only the dependency on the cms-dependencies artifact to the cms module. Make sure the new module is correctly linked into your Maven project. The dependencies section of the cms module should now look like this:

<dependency>
  <artifactId>myproject-cms-dependencies</artifactId>
  <groupId>${project.groupId}</groupId>
  <version>${project.version}</version>
  <type>pom</type>
</dependency>

9 - Adjust Essentials for Multi Delivery Webapp Mode

You're almost there. In order to make Essentials work with Single Delivery Webapp Mode, some project settings have been set up. These must be removed / reverted again in order to make Essentials interact successfully with a Multi Delivery Webapp Mode project.

With these steps in place, your project should now be Multi Delivery Webapp Mode-compliant, and build and run nicely.