Add a Second Delivery Webapp - Bloomreach Experience - Open Source CMS

This article covers a Hippo CMS version 13. There's an updated version available that covers our most recent release.

14-01-2020

Add a Second Delivery Webapp

Setting up multiple delivery web applications within the same project is intended to enable separate development teams working independently on their respective delivery webapps. Bloomreach recommends setting up multiple delivery web applications only in this specific development scenario. In all other cases, it is recommended to set up multiple channels within a single delivery web application.

Introduction

Goal

Add a second delivery web application to your existing Bloomreach Experience Manager implementation project.

Prerequisites

The tutorial assumes:

In addition, it is highly recommended to:

Approach

The second delivery webapp will be a separate Maven project with its own version management and release cycle but with a dependency on the 'parent' sub-project's CMS webapp.

In a real world development environment, the parent sub-project's artifacts would be deployed in your organizations Maven repository. For the purpose of this tutorial, you will use your local Maven repository as surrogate.

Following this tutorial, you will walk through a very basic multi delivery webapp development workflow scenario: create the second delivery webapp using the Maven archetype, add a feature to it, then migrate any platform code and/or configuration related to the new feature to the parent sub-project. The end result will be that the complete implementation project, including the parent sub-project and the delivery webapp sub-project) is ready for an aggregate deployment in an environment.

Create the Maven Project for the Second Delivery Webapp

First, navigate to the directory containing the existing project (myproject) and run the following Maven command:

mvn clean install

This deploys the project's artifacts in your local Maven repository so they are available when your build the new delivery webapp sub-project.

Navigate to a directory outside the existing project (e.g. its parent directory).

To create the second delivery webapp sub-project, type the command shown below. This will create a new folder with a name equal to the chosen artifactId, containing the generated sub-project. On Windows, run the command on a single line and leave out the line continuation characters ('\') or use '^' as continuation character.

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

Windows

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

The archetype plugin will ask you to confirm a number of properties defining the Maven coordinates for both 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: : 

If you are just following the tutorial and using the archetype default settings, press Enter to continue. Otherwise, enter 'N', then enter the appropriate values for your project.

Build and run the delivery webapp sub-project as you normally would for a single delivery webapp project:

cd mysiteproject
mvn clean verify
mvn -Pcargo.run -Drepo.path=storage

Note that the delivery webapp sub-project has its own CMS webapp (running at the usual URL, http://localhost:8080/cms/) which basically repackages the parent sub-project's CMS. This CMS webapp exists solely for the purpose of development within the delivery webapp sub-project. The same is true for the repository-data/application module.

The second delivery webapp will run at http://localhost:8080/mysiteproject/ although at this point there is nothing there yet.

Add a Feature to the Second Delivery Webapp

You are now ready to develop and test features in the delivery webapp sub-project. Because feature development is outside the scope of this tutorial, you will add an out-of-the-box feature from the Essentials library as an example.

Tip: before you add the feature, bring the delivery webapp sub-project code under version control (e.g. Git) so you can easily 'diff' afterwards to see what changes introduced by the new feature need to be migrated to the parent sub-project.

Browse to the Essentials dashboard at http://localhost:8080/essentials/ and install the 'Events' feature from the library.

Rebuild and restart the delivery webapp sub-project and check the CMS and the delivery webapp (at http://localhost:8080/mysiteproject/) to verify that the feature is installed and working correctly.

Note that up to this point, you have worked in complete isolation from the parent sub-project, i.e. your changes do not affect it. This is important, as it allows the parent sub-project to continue its own lifecycle of development, deployment, etc. without interference from any development going on in the delivery webapp sub-project.

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

Once the new feature in the delivery webapp sub-project is ready, any new code and/or configuration in the cms and repository-data/application modules must be migrated to the corresponding modules in the parent sub-project.

Adding the 'Events' feature did not introduce any CMS code, but it did add and modify several files within the repository-data/application module. 

The following files were added:

  • 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/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 all of the above files over to the corresponding folder within myproject/repository-data/application (create subfolders if necessary).

The following files were modified:

  • 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

You will have to manually merge the contents of the above 3 files into their counterparts in myproject/repository-data/application:

myproject/repository-data/application/src/main/resources/hcm-config/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
      

myproject/repository-data/application/src/main/resources/hcm-config/configuration/translations/templates.yaml (only English translations shown, merge other languages in a similar way):

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/>

myproject/repository-data/application/src/main/resources/hcm-config/configuration/translations/types.yaml (only English labels for eventsdocument shown, merge labels in other languages as well):

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 the changes, delete the 3 files from mysiteproject/repository-data/application. You can also delete any resulting empty folders.

Rebuild (mvn clean install) and restart the parent sub-project and browse to the CMS. Navigate to the Content perspective and select Document Types from the dropdown. The mysiteproject namespace should be there and contain the Event document type.

Stop the parent sub-project.

Delete the delivery webapp sub-project's storage folder, the rebuild and restart the delivery webapp sub-project. Verify that all the Events functionality (with the platform configuration now inherited from the parent sub-project) is still there and working as expected.

At this stage, you may want to test an aggregate deployment of the parent and delivery webapp sub-projects. In your local development environment, you can use the following Maven command to do this:

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

Browse to the CMS and verify that both delivery webapps can be previewed in the Channels perspective. Also verify that both the 'live' delivery webapps are available (on http://localhost:8080/site/ and http://localhost:8080/mysiteproject/) and fully functional.

If you want to deploy in a server environment (on-premise or Bloomreach Cloud), you need to create a distribution containing all three webapps (CMS and both delivery webapps). Add the mysiteproject webapp to the appropriate 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>

You can now create the distribution as usual:

mvn clean verify
mvn -P dist

Please note that content for the delivery webapp sub-project is not included in the distribution and will therefore not be bootstrapped on deployment. If you want to bootstrap some initial content (such as the mysiteproject root folder and the events folder), you would need to 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 would complicate development going forward so it may be better to create the content manually after the first deployment and keep the management of this type of repository data seperated between the sub-projects.

This completes a full multi delivery webapp development workflow cycle.

Additional Reading

Multi Delivery Webapp Development Workflow

Configure Multiple Delivery Webapps in Bloomreach Cloud

 

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?