Add a Second Delivery Webapp

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

Overview

This guide explains how to add a second delivery web application to an existing Bloomreach Content project.

When to Use

Set up a second delivery webapp when independent teams need to develop and release separate delivery applications within the same overall project. For most scenarios, managing multiple channels within a single delivery webapp is preferred.

Prerequisites

Before you start, ensure that:

You have completed the Get Started tutorial.
Your project was created using the standard Maven archetype with default property values, and includes the News and Simple Content features from the Essentials library.

Recommended:

Complete the Build a Website tutorial.
Review the Introduction to Multi Delivery Web Application Support.

Approach

The second delivery webapp will be a separate Maven project. It will have its own versioning and release cycle, but will depend on the parent sub-project's CMS webapp. In production, parent artifacts are deployed to your organization's Maven repository. For this tutorial, use your local Maven repository.

This guide walks through a basic multi delivery webapp development workflow: create the second delivery webapp, add a feature, and migrate platform code or configuration related to the new feature to the parent sub-project. The result is a project ready for aggregate deployment.

1. Create the Maven Project for the Second Delivery Webapp

In your existing project directory (myproject), run:
```
mvn clean install
```
This command installs the project's artifacts to your local Maven repository, making them available for the new delivery webapp sub-project.
Change to a directory outside the existing project (for example, the parent directory).

Generate the second delivery webapp sub-project using the Maven archetype. This creates a new folder named after your chosen artifactId.

For brXM v14:

mvn org.apache.maven.plugins:maven-archetype-plugin:2.4:generate \
-DarchetypeGroupId=org.onehippo.cms7 \
-DarchetypeArtifactId=hippo-site-project-archetype \
-DarchetypeVersion=14.7.27 \
-DarchetypeRepository=https://maven.bloomreach.com/repository/maven2/

Windows:

mvn org.apache.maven.plugins:maven-archetype-plugin:2.4:generate -DarchetypeGroupId=org.onehippo.cms7 -DarchetypeArtifactId=hippo-site-project-archetype -DarchetypeVersion=14.7.27 -DarchetypeRepository=https://maven.bloomreach.com/repository/maven2/

For brXM v15:

mvn org.apache.maven.plugins:maven-archetype-plugin:2.4:generate \
-DarchetypeGroupId=org.onehippo.cms7 \
-DarchetypeArtifactId=hippo-site-project-archetype \
-DarchetypeVersion=15.7.11 \
-DarchetypeRepository=https://maven.bloomreach.com/repository/maven2/

Windows:

mvn org.apache.maven.plugins:maven-archetype-plugin:2.4:generate -DarchetypeGroupId=org.onehippo.cms7 -DarchetypeArtifactId=hippo-site-project-archetype -DarchetypeVersion=15.7.11 -DarchetypeRepository=https://maven.bloomreach.com/repository/maven2/

The archetype plugin prompts you to confirm properties for the new delivery webapp sub-project and the existing parent sub-project:

Confirm properties configuration:
groupId: org.example.site
artifactId: mysiteproject
version: 0.1.0-SNAPSHOT
package: org.example.site
parentArtifactId: myproject
parentGroupId: org.example
parentVersion: 0.1.0-SNAPSHOT
projectName: My Site Project
 Y: :

Press Enter to accept the defaults or enter 'N' to provide custom values.

Build and run the delivery webapp sub-project:
```
cd mysiteproject
mvn clean verify
mvn -Pcargo.run -Drepo.path=./storage
```
The sub-project includes its own CMS webapp (at http://localhost:8080/cms/), which repackages the parent CMS for development purposes. The same applies to the repository-data/application module.

The new delivery webapp is available at http://localhost:8080/mysiteproject/, but does not yet contain any content.

2. Add a Feature to the Second Delivery Webapp

You can now develop and test features in the delivery webapp sub-project. This guide demonstrates adding an out-of-the-box feature from the Essentials library.

Hint: Before adding a feature, place the delivery webapp sub-project under version control (for example, Git). This allows you to compare changes introduced by the new feature and identify what needs to be migrated to the parent sub-project.

Open the Essentials dashboard at http://localhost:8080/essentials/.
Install the 'Events' feature from the library.
Rebuild and restart the delivery webapp sub-project.
Verify in the CMS and at http://localhost:8080/mysiteproject/ that the feature is installed and working.

At this stage, all changes are isolated to the delivery webapp sub-project. The parent sub-project remains unaffected and can continue its own development and deployment lifecycle.

3. Migrate CMS Configuration from the Delivery Webapp Sub-Project to the Parent Sub-Project

After developing the new feature, migrate any new code or configuration in the cms and repository-data/application modules to the corresponding modules in the parent sub-project.

For the 'Events' feature, no CMS code is added, but several files are created or modified in repository-data/application.

New files to move:

mysiteproject/repository-data/application/src/main/resources/hcm-config/namespaces/mysiteproject.cnd
mysiteproject/repository-data/application/src/main/resources/hcm-config/namespaces/mysiteproject.yaml
mysiteproject/repository-data/application/src/main/resources/hcm-config/namespaces/mysiteproject/basedocument.yaml
mysiteproject/repository-data/application/src/main/resources/hcm-config/namespaces/mysiteproject/eventsdocument.yaml
mysiteproject/repository-data/application/src/main/resources/hcm-config/configuration/modules/validation.yaml
mysiteproject/repository-data/application/src/main/resources/hcm-config/configuration/queries/templates/new-events-document.yaml
mysiteproject/repository-data/application/src/main/resources/hcm-config/configuration/queries/templates/new-events-folder.yaml
mysiteproject/repository-data/application/src/main/resources/hcm-config/configuration/translations/cms.yaml

Move these files to the corresponding locations in myproject/repository-data/application. Create subfolders if needed.

Files to merge manually:

mysiteproject/repository-data/application/src/main/resources/hcm-config/main.yaml
mysiteproject/repository-data/application/src/main/resources/hcm-config/configuration/translations/templates.yaml
mysiteproject/repository-data/application/src/main/resources/hcm-config/configuration/translations/types.yaml

Merge the contents of these files into their counterparts in myproject/repository-data/application.

Example for main.yaml:

definitions:
  namespace:
    myproject:
      uri: http://www.myproject.com/myproject/nt/1.0
      cnd: namespaces/myproject.cnd
    mysiteproject:
      uri: http://www.mysiteproject.com/mysiteproject/nt/1.0
      cnd: namespaces/mysiteproject.cnd

Example for configuration/translations/templates.yaml (English translations shown):

definitions:
  config:
    /hippo:configuration/hippo:translations/hippo:templates/de:
      # <snip/>
    /hippo:configuration/hippo:translations/hippo:templates/en:
      new-resource-bundle: new resource bundle
      new-untranslated-folder: new untranslated folder
      new-news-document: new news item
      new-news-folder: new news item folder
      new-content-folder: new content folder
      new-content-document: new content document
      new-events-folder: new events folder
      new-events-document: new event
    /hippo:configuration/hippo:translations/hippo:templates/fr:
      # <snip/>
    /hippo:configuration/hippo:translations/hippo:templates/nl:
      # <snip/>

Example for configuration/translations/types.yaml (English labels for eventsdocument):

definitions:
  config:
    /hippo:configuration/hippo:translations/hippo:types/myproject:newsdocument:
      jcr:primaryType: hipposys:resourcebundles
      /en:
        # <snip/>
      /nl:
        # <snip/>
      /de:
        # <snip/>
      /fr:
        # <snip/>
    /hippo:configuration/hippo:translations/hippo:types/myproject:contentdocument:
      jcr:primaryType: hipposys:resourcebundles
      /en:
        # <snip/>
      /nl:
        # <snip/>
      /fr:
        # <snip/>
      /de:
        # <snip/>
    /hippo:configuration/hippo:translations/hippo:types/mysiteproject:eventsdocument:
      jcr:primaryType: hipposys:resourcebundles
      /en:
        jcr:primaryType: hipposys:resourcebundle
        jcr:name: Event
        mysiteproject:content: Content
        mysiteproject:date: Start date
        mysiteproject:enddate: End date
        mysiteproject:image: Image
        mysiteproject:introduction: Introduction
        mysiteproject:location: Location
        mysiteproject:title: Title
      /nl:
        # <snip/>
      /fr:
        # <snip/>
      /de:
        # <snip/>

After merging, remove the three files from mysiteproject/repository-data/application. Delete any empty folders if present.

Rebuild the parent sub-project:

mvn clean install

Restart the parent sub-project and open the CMS. In the Content application, select Document Types from the dropdown. The mysiteproject namespace and the Event document type should appear.

Stop the parent sub-project.

Delete the delivery webapp sub-project's storage folder, then rebuild and restart the delivery webapp sub-project. Confirm that the Events functionality is still present and works as expected, now inheriting configuration from the parent sub-project.

To test aggregate deployment of both sub-projects locally:

mvn -Pcargo.run,with-main-site -Drepo.path=./storage

Verify in the CMS that both delivery webapps are available for preview in the Experience manager. Confirm that both live delivery webapps are running at http://localhost:8080/site/ and http://localhost:8080/mysiteproject/.

For deployment in a server environment (on-premise or Bloomreach Cloud), create a distribution containing the CMS and both delivery webapps. Add the mysiteproject webapp to your assembly file, for example:

myproject/src/main/assembly/webapps-component.xml

<component xmlns="http://maven.apache.org/plugins/maven-assembly-plugin/component/1.1.2" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
           xsi:schemaLocation="http://maven.apache.org/plugins/maven-assembly-plugin/component/1.1.2 http://maven.apache.org/xsd/component-1.1.2.xsd">
  <files>
    <file>
      <source>cms/target/cms.war</source>
      <outputDirectory>webapps</outputDirectory>
      <destName>cms.war</destName>
    </file>
    <file>
      <source>site/webapp/target/site.war</source>
      <outputDirectory>webapps</outputDirectory>
      <destName>site.war</destName>
    </file>
    <file>
      <source>../mysiteproject/site/webapp/target/site.war</source>
      <outputDirectory>webapps</outputDirectory>
      <destName>mysiteproject.war</destName>
    </file>
  </files>
</component>

Build the distribution as usual:

mvn clean verify
mvn -P dist

Note: Content for the delivery webapp sub-project is not included in the distribution and will not be bootstrapped on deployment. To bootstrap initial content (such as the mysiteproject root folder and the events folder), move the relevant YAML files from mysiteproject/repository-data/application/src/main/resources/hcm-content to myproject/repository-data/application/src/main/resources/hcm-content. However, this approach complicates ongoing development. Consider creating the content manually after the first deployment to keep repository data management separated between sub-projects.

This completes the multi delivery webapp development workflow.