AEM Local Development Setup

Luca Nerlich, aem

This posts describes the steps and software requirements one needs to follow, to create and setup a working, local AEM instance. Secondly, an example of using the "Maven Archetype" provides the necessary basics to bootstrap a new AEM project according to the best practices.

Table of Contents


  1. Install Java
    1. Download JDK
    2. Add to $PATH
  2. Login with Adobe Account & Download AEM
    1. Adobe Software Distribution
    2. e.g AEM SDK v2021.3.5087.20210322T071003Z-210325
    3. extract archive
  3. Start AEM Instance
    1. java -jar aem-sdk-quickstart-v2021.3.5087.20210322T071003Z-210325.jar -gui
    2. wait 1-5 minutes
  4. Install Maven
    1. Download
    2. Add to $PATH
  5. Execute Maven Archetype Command
    1. cd ./mysite
    2. mvn clean install -PautoInstallSinglePackage
  6. Access http://localhost:4502 and login via admin:admin


The following section describes the software needed to run a local AEM instance, as well as being able to start extending and customizing AEM.


This setup works for all latest major AEM Versions, including AEM as a Cloud Service, which is Adobes latest AEM offering. The Cloud SDK and 6.5 are in active development and receive new features on a regular basis. The Cloud SDK is being versioned via timestamps, such as aem-sdk-2021.3.5026.20210309T210727Z-210225, while the AEM On-Premise and Managed Services offerings still bear the classic major.minor.patch level notation.



A local development setup consists of two parts. One, the actual AEM instance (java process) running and secondly

Running AEM locally

After downloading the desired AEM Version from the Adobe Software Distribution, extract the archive - if the cloud sdk has been downloaded. Otherwise we can directly run the jar.

By renaming the jar according to the following schema, a couple of default settings can be set: cq-(author|publish)-p(port). For example cq-author-p4502. When started, this will run the AEM instance as an author and expose it locally via port 4502.

Running the jar is as easy as executing it like this: java -jar my-downloaded-aem.jar -gui. The parameter -gui can be appended, to launch an additional small UI, which informs the user about the startup / installation progress. Additionall, -gui will automatically set the default admin users credentials to admin:admin.

Bootstrapping a development environment via Maven Archetype

The Apache Maven Archetype describes Archetypes like this

[...] provide a system that provides a consistent means of generating Maven projects. Archetype will help authors create Maven project templates for users, and provides users with the means to generate parameterized versions of those project templates.

To summarize, by using an archetype, which itself has been created by the AEM Developer Team, we can set specific variables with which the archetypes bootstraps / creates a customized set of files and directories - ready to use.

The following example demonstrates a bash command using the v27 of the aem-project-archetype. By setting 'appTitle', 'appId' and 'groupId' we tell the Archetype how it should name and structure our packages. 'frontendModule' can be one of ['none', 'general', 'react', 'angular']. By specifying this parameter, we can opt in to use the (new) ui.frontend module, which itself can be preconfigures with either a "classic" html variant, or one of the modern Javascript SPA Frameworks - currently only React and Angular are supported.

If we do not specify an 'aemVersion' the latest AEM Cloud Sdk will be used. A specifiv version can be set via passing the AEM version in its major.minor.patch level notation. For example 'aemVersion="6.4.8' would create the archetype based on AEM 6.4 with Patch Level 8 and add all necessary dependencies to the pom.xml.

mvn -B archetype:generate \
-D archetypeGroupId=com.adobe.aem \
-D archetypeArtifactId=aem-project-archetype \
-D archetypeVersion=27 \
-D appTitle="My Site" \
-D appId="mysite" \
-D groupId="com.mysite" \
-D frontendModule=react \
-D includeExamples=y

The Archetypes provides a wide range of optional properties, with sensisble defaults set for each. For a list of all available settings, please check the official documentation on GitHub.

Executing the above command will create the following folder structure

Using AEM as a Cloud Service SDK version: 2021.3.5087.20210322T071003Z-210325
Creating content skeleton...
[INFO] Project created from Archetype in dir: /Users/nerlich/Downloads/temp/mysite
[INFO] ------------------------------------------------------------------------
[INFO] ------------------------------------------------------------------------
[INFO] Total time: 10.865 s
[INFO] Finished at: 2021-03-27T20:54:40+01:00
[INFO] ------------------------------------------------------------------------

cd mysite

-rw-r--r-- 1 nerlich staff 1.2K .gitignore
-rw-r--r-- 1 nerlich staff 11K LICENSE
-rw-r--r-- 1 nerlich staff 5.2K
drwxr-xr-x 4 nerlich staff 128B all/
drwxr-xr-x 3 nerlich staff 96B analyse/
-rw-r--r-- 1 nerlich staff 494B
drwxr-xr-x 4 nerlich staff 128B core/
drwxr-xr-x 6 nerlich staff 192B dispatcher/
drwxr-xr-x 4 nerlich staff 128B it.tests/
-rw-r--r-- 1 nerlich staff 28K pom.xml
drwxr-xr-x 5 nerlich staff 160B ui.apps/
drwxr-xr-x 4 nerlich staff 128B ui.apps.structure/
drwxr-xr-x 4 nerlich staff 128B ui.config/
drwxr-xr-x 4 nerlich staff 128B ui.content/
drwxr-xr-x 12 nerlich staff 384B ui.frontend/
drwxr-xr-x 11 nerlich staff 352B ui.tests/

Building and deploying the complete development environment can be done via the following command mvn clean install -PautoInstallSinglePackage - executed in the root directory.

ui.apps, ui.config and ui.content can be individually build with the profile -PautoInstallPackage. Deploying just the java module 'core' can be achieved with the profile -PautoInstallBundle.

Thanks for reading!


Links & Downloads

CC BY-NC 4.0  ©   Luca NerlichImprint + Privacy