Adobe Experience Manager (AEM) Maven Project

An Adobe Experience Manager (AEM) example to demonstrate creating and deploying a Maven Multi Module project using an aem-project-archetype. This tutorial was created for deployment using Java 11, Apache Maven 3.6.2, Maven AEM Project Archetype 22 and AEM version 6.5.

Requirements

More information

Optionally activate the adobe-public profile by default in user Maven settings. The settings.xml for Maven is usually located in the hidden .m2 user directory. To create project specific Maven settings, see Maven - Configuring for Projects.

settings.xml
<profile>
    <id>adobe-public</id>

    <activation>
        <activeByDefault>true</activeByDefault>
    </activation>

    ...
</profile>

Project

In a terminal, in your projects directory, create a directory for the source code. For eample, repo_base_foldername would be the root folder for your AEM project code repository.

cd repo_base_foldername

mkdir src

In the source code directory, use mvn to init the project with the desired archetype version. e.g.,

cd src

mvn archetype:generate \
 -Padobe-public \
 -DarchetypeGroupId=com.adobe.granite.archetypes \
 -DarchetypeArtifactId=aem-project-archetype \
 -DarchetypeVersion=22

If this is going to be a multilingual site, include property -DisSingleCountryWebsite=n. For default values, see the available properties section of the archetype. Use the -B option to skip the prompts and generate the project in batch mode. e.g.,

cd src

mvn archetype:generate -B \
 -Padobe-public \
 -DarchetypeGroupId=com.adobe.granite.archetypes \
 -DarchetypeArtifactId=aem-project-archetype \
 -DarchetypeVersion=22 \
 -DgroupId=com.adobe \
 -Dversion=0.0.1-SNAPSHOT \
 -DappsFolderName=myproject \
 -DartifactId=aem-dev-myproject \
 -Dpackage=com.adobe.aem.dev.myproject \
 -DartifactName=myproject \
 -DcomponentGroupName=myproject \
 -DconfFolderName=myproject \
 -DcontentFolderName=myproject \
 -DcssId=myproject \
 -DpackageGroup=myproject \
 -DsiteName=myproject

If you want to include the frontend build process based on Webpack with support for Sass and TypeScript / ES6, use option -DoptionIncludeFrontendModule=general in the archetype:generate. For more information, consult the aem-project-archetype-22/…/ui.frontend/README.md.

Answer the prompts to setup the project. for example,

Property Value
groupId com.adobe
version 0.0.1-SNAPSHOT
appsFolderName myproject
artifactId aem-dev-myproject
package com.adobe.aem.dev.myproject
artifactName myproject
componentGroupName myproject
confFolderName myproject
contentFolderName myproject
cssId myproject
packageGroup myproject
siteName myproject

The artifactId is used for the src maven project folder name. Typically, the groupId and artifactId combine to make the base package. However… NOTE, the base package value cannot contain hyphens. They will be evaluated as a minus sign operators during the Maven build and an error will be thrown. Therefore, we replace the hyphens with periods when combining the groupId and artifactId above. The Adobe WKND Tutorial Chapter, Project Setup contains more information including other examples on how to set up the archtype property values.

Project structure generated by the Maven archetype.

  • src
    • aem-dev-myproject
      • core
      • it.launcher
      • it.tests
      • pom.xml
      • README.md
      • ui.apps
      • ui.content
      • .gitignore

Package Thumbnail

If you would like to add a 64x64 square thumbnail.png image to the package so it is easily identified in AEM Package Manager, then follow this step.

Create a folder named definition in ui.apps/src/main/content/META-INF/vault

Copy your thumbnail.png file into the definition folder.

Also in the definition folder, add a file named .content.xml. with the following:

<?xml version="1.0" encoding="UTF-8"?>
<jcr:root xmlns:vlt="http://www.day.com/jcr/vault/1.0" xmlns:jcr="http://www.jcp.org/jcr/1.0" xmlns:nt="http://www.jcp.org/jcr/nt/1.0">
    <thumbnail.png/>
</jcr:root>

Repeat for ui.content/src/main/content/META-INF/vault

Deploy to AEM

Provided your AEM author instance is running at localhost:4502, navigate to the source project directory created with the artifactId name. e.g.,

cd aem-dev-myproject

mvn -PautoInstallPackage clean install

If your instance is on another port and/or uses non default admin credentials, pass those in as command line parameters. e.g.,

mvn -PautoInstallPackage -Daem.port=4702 -Dvault.username=admin -Dvault.password='secret' clean install

If you get [ERROR] Unresolveable build extension, try setting activateByDefault to true for the adobe-public profile in the Maven settings here.

If you get repository file read errors, locate the first one and note the file path. e.g.,

[INFO] -------------------------------------------------------------
[ERROR] COMPILATION ERROR :
[INFO] -------------------------------------------------------------
[ERROR] error reading /home/gilfoyle/.m2/repository/commons-beanutils/commons-beanutils/1.8.3/commons-beanutils-1.8.3.jar; zip END header not found

Delete the conflicting files from the repository. In this example, we’re deleting the 1.8.3 folder and its files under commons-beanutils

rm -rf /home/gilfoyle/.m2/repository/commons-beanutils/commons-beanutils/1.8.3

Run the mvn command again, this time with the update option. e.g.,

mvn -U -PautoInstallPackage clean install

The -U option will update the repository.

If everything works as expected, you should get output similar to the following:

[INFO] ------------------------------------------------------------------------
[INFO] Reactor Summary for aem-dev-myproject 0.0.1-SNAPSHOT:
[INFO]
[INFO] aem-dev-myproject .................................. SUCCESS [  0.244 s]
[INFO] myproject - Core ................................... SUCCESS [  5.921 s]
[INFO] myproject - Repository Structure Package ........... SUCCESS [  0.633 s]
[INFO] myproject - UI apps ................................ SUCCESS [  2.804 s]
[INFO] myproject - UI content ............................. SUCCESS [  2.496 s]
[INFO] myproject - All .................................... SUCCESS [  1.305 s]
[INFO] myproject - Integration Tests Bundles .............. SUCCESS [  1.191 s]
[INFO] myproject - Integration Tests Launcher ............. SUCCESS [  0.953 s]
[INFO] ------------------------------------------------------------------------
[INFO] BUILD SUCCESS
[INFO] ------------------------------------------------------------------------
[INFO] Total time:  16.467 s
[INFO] Finished at: 2019-12-10T20:55:41-05:00
[INFO] ------------------------------------------------------------------------

Verify the package deployment and installation. For example, open the Package Manager at localhost:4502/crx/packmgr. For this archetype, you should see, aem-dev-myproject.all, aem-dev-myproject.ui.content and aem-dev-myproject.ui.apps packages version 0.0.1-SNAPSHOT installed.

AEM CRX Package Manager

You can do also perform incremental build deployments after making updates. These will run faster since their scope is smaller. e.g.,

cd ui.apps

mvn -PautoInstallPackage -Padobe-public clean install

Core Components

AEM Core Components are included in the project.

To update these components, edit the project pom.xml. For example, in aem-dev-myproject/pom.xml, change the core.wcm.components.version property to 2.8.0. Then run mvn -PautoInstallPackage clean install to deploy the new version of the core components. e.g.,

cd aem-dev-myproject

mvn -PautoInstallPackage clean install

Verify in Package Manager.

AEM CRX Package Manager - Core Components

Additional Reading

Part 1 of 4 in the AEM Maven Project series.

Adobe Experience Manager (AEM) Maven Project Part II

comments powered by Disqus