Documentation AEM AEM Tutorials AEM Sites WKND Tutorials

Project Setup project-setup

Last update: Thu Jan 25 2024 00:00:00 GMT+0000 (Coordinated Universal Time)

Topics:
AEM Project Archetype

CREATED FOR:

Beginner
Developer

This tutorial covers the creation of a Maven Multi Module Project to manage the code and configurations for an Adobe Experience Manager Site.

Prerequisites prerequisites

Review the required tooling and instructions for setting up a local development environment. Ensure that you have a fresh instance of Adobe Experience Manager available locally and that no additional sample/demo packages have been installed (other than required Service Packs).

Objective objective

Learn how to generate a new AEM project using a Maven archetype.
Understand the different modules generated by the AEM Project Archetype and how they work together.
Understand how AEM Core Components are included in an AEM Project.

What you are going to build what-build

https://video.tv.adobe.com/v/30152?quality=12&learn=on

Transcript

Hello. In this chapter you’ll generate a new Adobe Experience Manager project. This project will contain all of the code, content, and configurations for you AEM site’s implementation, and it’s designed to be installed on top of AEM. We’ll use a tool called the AEM project archetype to generate our project. The AEM project archetype is a maven archetype, and this can be thought of as a pattern or template for creating new projects. It’s open-source and can be found on KitHub. It represents Adobe’s recommended best practices for starting an AEM project.

Now, before you begin, you will need to have a locally running instance of AEM running on port 4502. You will also need the following tools installed and configured to be available from the command line. You’ll need, at a minimum, Java 8, preferably Java 11. You will also need Apache Maven at a minimum of 3.39 for the version. -

In this chapter, you generate a new Adobe Experience Manager project using the AEM Project Archetype. Your AEM project contains complete code, content, and configurations used for a Sites implementation. The project generated in this chapter serves as the basis for an implementation of the WKND Site and are built upon in future chapters.

What is a Maven project? - Apache Maven is a software management tool to build projects. All Adobe Experience Manager implementations use Maven projects to build, manage, and deploy custom code on top of AEM.

What is a Maven archetype? - A Maven archetype is a template or pattern for generating new projects. The AEM Project archetype helps to generate a new project with a custom namespace and include a project structure that follows best practices, greatly accelerating the project development.

Create the project create

There are a couple options for creating a Maven Multi-module project for AEM. This tutorial uses the Maven AEM Project Archetype 35. Cloud Manager also provides a UI wizard to initiate the creation of an AEM application project. The underlying project generated by the Cloud Manager UI results in the same structure as using the archetype directly.

NOTE

This tutorial uses version 35 of the archetype. It is always a best practice to use the latest version of the archetype to generate a new project.

The next series of steps will take place using a UNIX® based command-line terminal, but should be similar if using a Windows terminal.

Open up a command-line terminal. Verify that Maven is installed:

code language-shell
`$ mvn --version Apache Maven 3.6.2 Maven home: /Library/apache-maven-3.6.2 Java version: 11.0.4, vendor: Oracle Corporation, runtime: /Library/Java/JavaVirtualMachines/jdk-11.0.4.jdk/Contents/Home`

Navigate to a directory in which you want to generate the AEM project. This can be any directory in which you want to maintain your project’s source code. For example, a directory named code beneath the user’s home directory:

code language-shell
`$ cd ~/code`

Paste the following into the command line to generate the project in batch mode:

code language-shell

code language-shell
`mvn -B org.apache.maven.plugins:maven-archetype-plugin:3.2.1:generate \ -D archetypeGroupId=com.adobe.aem \ -D archetypeArtifactId=aem-project-archetype \ -D archetypeVersion=39 \ -D appTitle="WKND Sites Project" \ -D appId="wknd" \ -D groupId="com.adobe.aem.guides" \ -D artifactId="aem-guides-wknd" \ -D package="com.adobe.aem.guides.wknd" \ -D version="0.0.1-SNAPSHOT" \ -D aemVersion="cloud"`

mvn -B org.apache.maven.plugins:maven-archetype-plugin:3.2.1:generate \
    -D archetypeGroupId=com.adobe.aem \
    -D archetypeArtifactId=aem-project-archetype \
    -D archetypeVersion=39 \
    -D appTitle="WKND Sites Project" \
    -D appId="wknd" \
    -D groupId="com.adobe.aem.guides" \
    -D artifactId="aem-guides-wknd" \
    -D package="com.adobe.aem.guides.wknd" \
    -D version="0.0.1-SNAPSHOT" \
    -D aemVersion="cloud"

note note
NOTE
To target AEM 6.5.14+ replace `aemVersion="cloud"` with `aemVersion="6.5.14"`.
Also, always use the latest `archetypeVersion` by referring to the AEM Project Archetype > Usage

A full list of available properties for configuring a project can be found here.

The following folder and file structure is generated by the Maven archetype on your local file system:

code language-plain

code language-plain
`~/code/ \|--- aem-guides-wknd/ \|--- all/ \|--- core/ \|--- ui.apps/ \|--- ui.apps.structure/ \|--- ui.config/ \|--- ui.content/ \|--- ui.frontend/ \|--- ui.tests / \|--- it.tests/ \|--- dispatcher/ \|--- pom.xml \|--- README.md \|--- .gitignore`

 ~/code/
    |--- aem-guides-wknd/
        |--- all/
        |--- core/
        |--- ui.apps/
        |--- ui.apps.structure/
        |--- ui.config/
        |--- ui.content/
        |--- ui.frontend/
        |--- ui.tests /
        |--- it.tests/
        |--- dispatcher/
        |--- pom.xml
        |--- README.md
        |--- .gitignore

Deploy and build the project build

Build and deploy the project code to a local instance of AEM.

Ensure you have an author instance of AEM running locally on port 4502.

From the command line, navigate into the aem-guides-wknd project directory.

code language-shell
`$ cd aem-guides-wknd`

Run the following command to build and deploy the entire project to AEM:

code language-shell
`$ mvn clean install -PautoInstallSinglePackage`

The build takes around a minute and should end with the following message:

code language-none

code language-none
... [INFO] ------------------------------------------------------------------------ [INFO] Reactor Summary for WKND Sites Project 0.0.1-SNAPSHOT: [INFO] [INFO] WKND Sites Project ................................. SUCCESS [ 0.113 s] [INFO] WKND Sites Project - Core .......................... SUCCESS [ 3.136 s] [INFO] WKND Sites Project - UI Frontend ................... SUCCESS [ 4.461 s] [INFO] WKND Sites Project - Repository Structure Package .. SUCCESS [ 0.359 s] [INFO] WKND Sites Project - UI apps ....................... SUCCESS [ 1.732 s] [INFO] WKND Sites Project - UI content .................... SUCCESS [ 0.956 s] [INFO] WKND Sites Project - UI config ..................... SUCCESS [ 0.064 s] [INFO] WKND Sites Project - All ........................... SUCCESS [ 8.229 s] [INFO] WKND Sites Project - Integration Tests ............. SUCCESS [ 3.329 s] [INFO] WKND Sites Project - Dispatcher .................... SUCCESS [ 0.027 s] [INFO] WKND Sites Project - UI Tests ...................... SUCCESS [ 0.032 s] [INFO] ------------------------------------------------------------------------ [INFO] BUILD SUCCESS [INFO] ------------------------------------------------------------------------ [INFO] Total time: 23.189 s [INFO] Finished at: 2023-01-10T11:12:23-05:00 [INFO] ------------------------------------------------------------------------

...
[INFO] ------------------------------------------------------------------------
[INFO] Reactor Summary for WKND Sites Project 0.0.1-SNAPSHOT:
[INFO]
[INFO] WKND Sites Project ................................. SUCCESS [  0.113 s]
[INFO] WKND Sites Project - Core .......................... SUCCESS [  3.136 s]
[INFO] WKND Sites Project - UI Frontend ................... SUCCESS [  4.461 s]
[INFO] WKND Sites Project - Repository Structure Package .. SUCCESS [  0.359 s]
[INFO] WKND Sites Project - UI apps ....................... SUCCESS [  1.732 s]
[INFO] WKND Sites Project - UI content .................... SUCCESS [  0.956 s]
[INFO] WKND Sites Project - UI config ..................... SUCCESS [  0.064 s]
[INFO] WKND Sites Project - All ........................... SUCCESS [  8.229 s]
[INFO] WKND Sites Project - Integration Tests ............. SUCCESS [  3.329 s]
[INFO] WKND Sites Project - Dispatcher .................... SUCCESS [  0.027 s]
[INFO] WKND Sites Project - UI Tests ...................... SUCCESS [  0.032 s]
[INFO] ------------------------------------------------------------------------
[INFO] BUILD SUCCESS
[INFO] ------------------------------------------------------------------------
[INFO] Total time:  23.189 s
[INFO] Finished at: 2023-01-10T11:12:23-05:00
[INFO] ------------------------------------------------------------------------

The Maven profile autoInstallSinglePackage compiles the individual modules of the project and deploys a single package to the AEM instance. By default this package is deployed to an AEM instance running locally on port 4502 and with the credentials of admin:admin.

Navigate to Package Manager on your local AEM instance: http://localhost:4502/crx/packmgr/index.jsp. You should see packages for aem-guides-wknd.ui.apps, aem-guides-wknd.ui.config, aem-guides-wknd.ui.content, and aem-guides-wknd.all.
Navigate to the Sites console: http://localhost:4502/sites.html/content. The WKND Site is one of the sites. It includes a site structure with a US and Language Masters hierarchy. This site hierarchy is based on the values for language_country and isSingleCountryWebsite when generating the project using the archetype.
Open the US > English page by selecting the page and clicking the Edit button in the menu bar:
Starter content has already been created and several components are available to be added to a page. Experiment with these components to get an idea of the functionality. You will learn the basics of a component in the next chapter.

Sample content generated by the Archetype

Inspect the project project-structure

The generated AEM project is made up of individual Maven modules, each with a different role. This tutorial and most development focus on these modules:

core - Java Code, primarily back-end developers.
ui.frontend - Contains source code for CSS, JavaScript, Sass, TypeScript, primarily for front-end developers.
ui.apps - Contains component and dialog definitions, embeds compiled CSS and JavaScript as client libraries.
ui.content - contains structural content and configurations like editable templates, metadata schemas (https://experienceleague.adobe.com/content,%20/conf?lang=en).
all - this is an empty Maven module that combines the above modules into a single package that can be deployed to an AEM environment.

Maven Project Diagram

See the AEM Project Archetype documentation to learn more details of all the Maven modules.

Inclusion of Core Components core-components

AEM Core Components are a set of standardized Web Content Management (WCM) components for AEM. These components provide a baseline set of a functionality and are styled, customized, and extended for individual projects.

AEM as a Cloud Service environment include the latest version of AEM Core Components. Therefore projects generated for AEM as a Cloud Service do not include an embed of AEM Core Components.

For AEM 6.5/6.4 generated projects, the archetype automatically embeds AEM Core Components in the project. It is a best practice for AEM 6.5/6.4 to embed AEM Core Components to ensure that the latest version gets deployed with your project. More information about how Core Components are included in the project can be found here.

Source Control Management source-control

It is always a good idea to use some form of source control to manage the code in your application. This tutorial uses git and GitHub. There are several files that get generated by Maven and/or the IDE of choice that should be ignored by the SCM.

Maven creates a target folder whenever you build and install the code package. The target folder and contents should be excluded from SCM.

Under, the ui.apps module observe that many .content.xml files are created. These XML files map the node types and properties of content installed in the JCR. These files are critical and cannot be ignored.

The AEM project archetype generates a sample .gitignore file that can be used as a starting point for which files can be safely ignored. The file is generated at <src>/aem-guides-wknd/.gitignore.

Congratulations! congratulations

Congratulations, you have created your first AEM Project!

Next Steps next-steps

Understand the underlying technology of an Adobe Experience Manager (AEM) Sites Component through a simple HelloWorld example with the Component Basics tutorial.

Advanced Maven commands (Bonus) advanced-maven-commands

During development, you may be working with just one of the modules and want to avoid building the entire project in order to save time. You may also want to deploy directly to an AEM Publish instance or perhaps to an instance of AEM not running on port 4502.

Next let’s review some additional Maven profiles and commands you can use for greater flexibility during development.

Core module core-module

The core module contains all Java™ code associated with the project. The build of core module deploys an OSGi bundle to AEM. To build just this module:

Navigate into the core folder (beneath aem-guides-wknd):

code language-shell
`$ cd core/`

Run the following command:

code language-shell

code language-shell
$ mvn clean install -PautoInstallBundle ... [INFO] --- sling-maven-plugin:2.4.0:install (install-bundle) @ aem-guides-wknd.core --- [INFO] Installing Bundle aem-guides-wknd.core(~/code/aem-guides-wknd/core/target/aem-guides-wknd.core-0.0.1-SNAPSHOT.jar) to http://localhost:4502/system/console via WebConsole [INFO] Bundle installed [INFO] ------------------------------------------------------------------------ [INFO] BUILD SUCCESS [INFO] ------------------------------------------------------------------------ [INFO] Total time: 8.558 s

$ mvn clean install -PautoInstallBundle
...
[INFO] --- sling-maven-plugin:2.4.0:install (install-bundle) @ aem-guides-wknd.core ---
[INFO] Installing Bundle aem-guides-wknd.core(~/code/aem-guides-wknd/core/target/aem-guides-wknd.core-0.0.1-SNAPSHOT.jar) to http://localhost:4502/system/console via WebConsole
[INFO] Bundle installed
[INFO] ------------------------------------------------------------------------
[INFO] BUILD SUCCESS
[INFO] ------------------------------------------------------------------------
[INFO] Total time:  8.558 s

Navigate to http://localhost:4502/system/console/bundles. This is the OSGi Web console and contains information about all the bundles installed on the AEM instance.
Toggle the Id sort column and you should see the WKND bundle installed and active.
You can see the ‘physical’ location of the jar in CRXDE-Lite:

Ui.apps and Ui.content modules apps-content-module

The ui.apps maven module contains all the rendering code needed for the site beneath /apps. This includes CSS/JS that is stored in an AEM format called clientlibs. This also includes HTL scripts for rendering dynamic HTML. You can think of the ui.apps module as a map to the structure in the JCR but in a format that can be stored on a file system and committed to source control. The ui.apps module only contains code.

To build just this module:

From the command line. Navigate into the ui.apps folder (beneath aem-guides-wknd):

code language-shell
`$ cd ../ui.apps`

Run the following command:

code language-shell

code language-shell
`$ mvn clean install -PautoInstallPackage ... Package installed in 70ms. [INFO] ------------------------------------------------------------------------ [INFO] BUILD SUCCESS [INFO] ------------------------------------------------------------------------ [INFO] Total time: 2.987 s [INFO] Finished at: 2023-01-10T11:35:28-05:00 [INFO] ------------------------------------------------------------------------`

$ mvn clean install -PautoInstallPackage
...
Package installed in 70ms.
[INFO] ------------------------------------------------------------------------
[INFO] BUILD SUCCESS
[INFO] ------------------------------------------------------------------------
[INFO] Total time:  2.987 s
[INFO] Finished at: 2023-01-10T11:35:28-05:00
[INFO] ------------------------------------------------------------------------

Navigate to http://localhost:4502/crx/packmgr/index.jsp. You should see the ui.apps package as the first installed package and it should have a more recent timestamp than any of the other packages.

Return to the command line and run the following command (within the ui.apps folder):

code language-shell

code language-shell
$ mvn -PautoInstallPackagePublish clean install ... [INFO] --- content-package-maven-plugin:1.0.2:install (install-package-publish) @ aem-guides-wknd.ui.apps --- [INFO] Installing aem-guides-wknd.ui.apps (/Users/sachinmali/Desktop/code/wknd-tutorial/aem-guides-wknd/ui.apps/target/aem-guides-wknd.ui.apps-0.0.1-SNAPSHOT.zip) to http://localhost:4503/crx/packmgr/service.jsp [INFO] I/O exception (java.net.ConnectException) caught when processing request: Connection refused (Connection refused) [INFO] Retrying request [INFO] I/O exception (java.net.ConnectException) caught when processing request: Connection refused (Connection refused) [INFO] Retrying request [INFO] I/O exception (java.net.ConnectException) caught when processing request: Connection refused (Connection refused) [INFO] Retrying request [INFO] ------------------------------------------------------------------------ [INFO] BUILD FAILURE [INFO] ------------------------------------------------------------------------ [INFO] Total time: 2.812 s [INFO] Finished at: 2023-01-10T11:37:28-05:00 [INFO] ------------------------------------------------------------------------ [ERROR] Failed to execute goal com.day.jcr.vault:content-package-maven-plugin:1.0.2:install (install-package-publish) on project aem-guides-wknd.ui.apps: Connection refused (Connection refused) -> [Help 1]

$ mvn -PautoInstallPackagePublish clean install
...
[INFO] --- content-package-maven-plugin:1.0.2:install (install-package-publish) @ aem-guides-wknd.ui.apps ---
[INFO] Installing aem-guides-wknd.ui.apps (/Users/sachinmali/Desktop/code/wknd-tutorial/aem-guides-wknd/ui.apps/target/aem-guides-wknd.ui.apps-0.0.1-SNAPSHOT.zip) to http://localhost:4503/crx/packmgr/service.jsp
[INFO] I/O exception (java.net.ConnectException) caught when processing request: Connection refused (Connection refused)
[INFO] Retrying request
[INFO] I/O exception (java.net.ConnectException) caught when processing request: Connection refused (Connection refused)
[INFO] Retrying request
[INFO] I/O exception (java.net.ConnectException) caught when processing request: Connection refused (Connection refused)
[INFO] Retrying request
[INFO] ------------------------------------------------------------------------
[INFO] BUILD FAILURE
[INFO] ------------------------------------------------------------------------
[INFO] Total time:  2.812 s
[INFO] Finished at: 2023-01-10T11:37:28-05:00
[INFO] ------------------------------------------------------------------------
[ERROR] Failed to execute goal com.day.jcr.vault:content-package-maven-plugin:1.0.2:install (install-package-publish) on project aem-guides-wknd.ui.apps: Connection refused (Connection refused) -> [Help 1]

The profile autoInstallPackagePublish is intended to deploy the package to a Publish environment running on port 4503. The above error is expected if an AEM instance running on http://localhost:4503 cannot be found.

Finally run the following command to deploy the ui.apps package on port 4504:

code language-shell

code language-shell
$ mvn -PautoInstallPackage clean install -Daem.port=4504 ... [INFO] --- content-package-maven-plugin:1.0.2:install (install-package) @ aem-guides-wknd.ui.apps --- [INFO] Installing aem-guides-wknd.ui.apps (/Users/dgordon/code/aem-guides-wknd/ui.apps/target/aem-guides-wknd.ui.apps-0.0.1-SNAPSHOT.zip) to http://localhost:4504/crx/packmgr/service.jsp [INFO] I/O exception (java.net.ConnectException) caught when processing request: Connection refused (Connection refused) [INFO] Retrying request [INFO] I/O exception (java.net.ConnectException) caught when processing request: Connection refused (Connection refused) [INFO] Retrying request [INFO] I/O exception (java.net.ConnectException) caught when processing request: Connection refused (Connection refused) [INFO] Retrying request [INFO] ------------------------------------------------------------------------ [INFO] BUILD FAILURE [INFO] --------------------------------------------------------------------

$ mvn -PautoInstallPackage clean install -Daem.port=4504
...
[INFO] --- content-package-maven-plugin:1.0.2:install (install-package) @ aem-guides-wknd.ui.apps ---
[INFO] Installing aem-guides-wknd.ui.apps (/Users/dgordon/code/aem-guides-wknd/ui.apps/target/aem-guides-wknd.ui.apps-0.0.1-SNAPSHOT.zip) to http://localhost:4504/crx/packmgr/service.jsp
[INFO] I/O exception (java.net.ConnectException) caught when processing request: Connection refused (Connection refused)
[INFO] Retrying request
[INFO] I/O exception (java.net.ConnectException) caught when processing request: Connection refused (Connection refused)
[INFO] Retrying request
[INFO] I/O exception (java.net.ConnectException) caught when processing request: Connection refused (Connection refused)
[INFO] Retrying request
[INFO] ------------------------------------------------------------------------
[INFO] BUILD FAILURE
[INFO] --------------------------------------------------------------------

Again a build failure is expected to occur if no AEM instance running on port 4504 is available. The parameter aem.port is defined in the POM file at aem-guides-wknd/pom.xml.

The ui.content module is structured the same way as the ui.apps module. The only difference is that the ui.content module contains what is known as mutable content. Mutable content essentially refers to non-code configurations like Templates, Policies, or folder structures that is stored in source-control but could be modified on an AEM instance directly. This is explored in more detail in the chapter on Pages and Templates.

The same Maven commands used to build the ui.apps module can be used to build the ui.content module. Feel free to repeat the above steps from within the ui.content folder.

Troubleshooting

If there is issue generating the project using the AEM Project Archetype see the list of known issues and list of open issues.

Congratulations again! congratulations-bonus

Congratulations, on going through the bonus material.

Next Steps next-steps-bonus

Understand the underlying technology of an Adobe Experience Manager (AEM) Sites Component through a simple HelloWorld example with the Component Basics tutorial.

recommendation-more-help

b2a561c1-47c0-4182-b8c1-757a197484f9