Add a Second Delivery Webapp
Introduction
Goal
Add a second delivery web application to your existing Bloomreach Experience Manager implementation project.
Prerequisites
The tutorial assumes:
- You have at least followed the Get Started tutorial.
- Your existing project is a standard project created using the Maven archetype with default archetype property values and the News and Simple Content features added from the Essentials library.
In addition, it is highly recommended to:
- Follow the Build a Website tutorial.
- Read the Introduction to Multi Delivery Web Application Support.
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.
Bloomreach Experience Manager v14
mvn org.apache.maven.plugins:maven-archetype-plugin:2.4:generate \ -DarchetypeGroupId=org.onehippo.cms7 \ -DarchetypeArtifactId=hippo-site-project-archetype \ -DarchetypeVersion=14.7.18 \ -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.18 -DarchetypeRepository=https://maven.bloomreach.com/repository/maven2/
Bloomreach Experience Manager v15
mvn org.apache.maven.plugins:maven-archetype-plugin:2.4:generate \ -DarchetypeGroupId=org.onehippo.cms7 \ -DarchetypeArtifactId=hippo-site-project-archetype \ -DarchetypeVersion=15.5.0 \ -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.5.0 -DarchetypeRepository=https://maven.bloomreach.com/repository/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.
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/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 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 application 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 Experience manager. 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