ÃÛ¶¹ÊÓÆµ

Set up a Local AEM Development Environment

Guide to setting up a local development for ÃÛ¶¹ÊÓÆµ Experience Manager, AEM. Covers important topics of local installation, Apache Maven, integrated development environments and debugging/troubleshooting. Development with Eclipse IDE, CRXDE Lite, Visual Studio Code, and IntelliJ are discussed.

Overview

Setting up a local development environment is the first step when developing for ÃÛ¶¹ÊÓÆµ Experience Manager or AEM. Take the time to set up a quality development environment to increase your productivity and write better code, faster. We can break an AEM local development environment into four areas:

  • Local AEM instances
  • Apache Maven project
  • Integrated Development Environments (IDE)
  • Troubleshooting

Install local AEM Instances

When we refer to a local AEM instance, we are talking about a copy of ÃÛ¶¹ÊÓÆµ Experience Manager that is running on a developer’s personal machine. All AEM development should start by writing and running code against a local AEM instance.

If you are new to AEM, there are two basic run modes can be installed: Author and Publish. The Author runmode is the environment that digital marketers use to create and manage content. When developing most of the time, you are deploying code to an Author instance. This allows you to create pages and add and configure components. AEM Sites is a WYSIWYG authoring CMS and therefore most of the CSS and JavaScript can be tested against an authoring instance.

It is also critical test code against a local Publish instance. The Publish instance is the AEM environment that visitors to your website interact with. While the Publish instance is the same technology stack as the Author instance, there are some major distinctions with configurations and permissions. The code must be tested against a local Publish instance before being promoted to higher-level environments.

Steps

  1. Ensure that Javaâ„¢ is installed.

    • Prefer for AEM 6.5+
    • for AEM versions before AEM 6.5
  2. Get a copy of the AEM QuickStart Jar and a license.properties.

  3. Create a folder structure on your computer like the following:

~/aem-sdk
    /author
    /publish
  1. Rename the QuickStart JAR to aem-author-p4502.jar and place it beneath the /author directory. Add the license.properties file beneath the /author directory.

  2. Make a copy of the QuickStart JAR, rename it to aem-publish-p4503.jar and place it beneath the /publish directory. Add a copy of the license.properties file beneath the /publish directory.

~/aem-sdk
    /author
        + aem-author-p4502.jar
        + license.properties
    /publish
        + aem-publish-p4503.jar
        + license.properties
  1. Double-click the aem-author-p4502.jar file to install the Author instance. This starts the author instance, running on port 4502 on the local computer.

Double-click the aem-publish-p4503.jar file to install the Publish instance. This starts the Publish instance, running on port 4503 on the local computer.

NOTE
Depending on your development machine’s hardware, it may be difficult to have both an Author and Publish instance running at the same time. Rarely do you need to run both simultaneously on a local setup.

Using command line

An alternative to double clicking the JAR file is to launch AEM from the command line or create a script (.bat or .sh) depending on your local operating system flavor. Below is an example of the sample command:

$ java -Xmx2048M -Xdebug -Xnoagent -Djava.compiler=NONE -Xrunjdwp:transport=dt_socket,server=y,suspend=n,address=30303 -jar aem-author-p4502.jar -gui -r"author,localdev"

Here, the -X are JVM options and -D are additional framework properties, for more information, see Deploying and Maintaining an AEM instance and Further options available from the Quickstart file.

Install Apache Maven

Apache Maven is a tool to manage the build and deploy procedure for Java-based projects. AEM is a Java-based platform and Maven is the standard way to manage code for an AEM project. When we say AEM Maven Project or just your AEM Project, we are referring to a Maven project that includes all the custom code for your site.

All AEM Projects should be built off the latest version of the AEM Project Archetype: . The AEM Project Archetype provides a bootstrap of an AEM project with some sample code and content. The AEM Project Archetype also includes AEM WCM Core Components configured to be used on your project.

CAUTION
When starting a new project, it is a best practice to use the latest version of the archetype. Keep in mind that there are multiple versions of the archetype and not all versions are compatible with earlier versions of AEM.

Steps

  1. Download
  2. Install and ensure that the installation has been added to your command-line PATH.
    • macOS users can install Maven using
  3. Verify that Maven is installed by opening a new command-line terminal and executing the following:

$ mvn --version
Apache Maven 3.3.9
Maven home: /Library/apache-maven-3.3.9
Java version: 1.8.0_111, vendor: Oracle Corporation
Java home: /Library/Java/JavaVirtualMachines/jdk1.8.0_111.jdk/Contents/Home/jre
Default locale: en_US, platform encoding: UTF-8
NOTE
In, the past addition of adobe-public Maven profile was needed to point nexus.adobe.com to download AEM artifacts. All AEM artifacts are now available via Maven Central and the adobe-public profile is not needed.

Set Up an Integrated Development Environment

An integrated development environment or IDE is an application that combines a text editor, syntax support, and build-tools. Depending on the type of development you are doing, one IDE might be preferable over another. Regardless of the IDE, it is important to be able to periodically push code to a local AEM instance in order to test it. It is important to occasionally pull configurations from a local AEM instance into your AEM project in order to persist to a source-control management system like Git.

Below are a few of the more popular IDEs that are used with AEM development with corresponding videos that show the integration with a local AEM instance.

NOTE
The WKND Project has been updated to default to work on AEM as a Cloud Service. It has been updated to be . If using AEM 6.5 or 6.4, append the classic profile to any Maven commands.
$ mvn clean install -PautoInstallSinglePackage -Pclassic

When, using an IDE please make sure to check classic in your Maven Profile tab.

Maven Profile Tab

IntelliJ Maven Profile

Eclipse IDE

The is one of the more popular IDEs for Javaâ„¢ development, in large part because it is open source and free! ÃÛ¶¹ÊÓÆµ provides a plugin, AEM Developer Tools, for Eclipse to allow easier development with a nice GUI to synchronize code with a local AEM instance. The Eclipse IDE is recommended for developers new to AEM in large part because of the GUI support by AEM Developer Tools.

Installation and Setup

  1. Download and install the Eclipse IDE for Javaâ„¢ EE Developers:
  2. Follow the instructions to install the AEM Developer Tools plugin: /docs/experience-manager-65/developing/devtools/aem-eclipse.html

video poster

  • 00:30 - Import Maven Project
  • 01:24 - Build and deploy source code with Maven
  • 04:33 - Push code changes with AEM Developer Tool
  • 10:55 - Pull code changes with AEM Developer Tool
  • 13:12 - Using the integrated debugging tools of Eclipse

IntelliJ IDEA

The is a powerful IDE for professional Javaâ„¢ development. IntelliJ IDEA comes in two flavors, a free Community edition and a commercial (paid) Ultimate version. The free Community version of IntellIJ IDEA is sufficient for more AEM development, however the Ultimate .

Installation and Setup

  1. Download and install the IntelliJ IDEA:
  2. Install Repo (command-line tool):