• Global. Remote. Office-free.
  • Mon – Fri: 8:00 AM to 5:00 PM (Hong Kong Time)
English

Warning: foreach() argument must be of type array|object, bool given in /var/www/html/wp-content/plugins/wp-builder/core/Components/ShiftSaas/Global/topbar.php on line 50
Los Angeles Branch

Setting Up AEM SDK and Local Environment

By Vuong Nguyen September 13, 2025 14 min read

Setting Up Your Local AEM Development Environment

First and most importantly, you need an Adobe Experience Cloud account that is linked to a specific program in order to access resources such as the Software Distribution portal.

For example, in the screenshot below, my account is associated with Adobe’s client program (Flagtick), which provides access to services like Adobe Experience Manager. This setup ensures you can download and configure the local AEM SDK for your environment.

Once your account’s linked to a program, just head over to the Software Distribution portal to grab the AEM SDK and other tools. The page (screenshot below) makes it easy to search, filter, and pick the right version for your setup.

When you are in the portal, you will see a list of available AEM SDK versions, each with details like file size, type, and release date (screenshot below).

It is usually best to grab the latest version to make sure you are working with the most up-to-date features and fixes, but older builds are also available if you need them for compatibility.

After downloading, you will get a compressed zip file of the AEM SDK saved locally (as shown below). In this example, the aem-sdk-latest-version.zip file is stored under the C:\aem-sdk folder.

This package contains everything you need to set up and run AEM locally, and the next step will be to extract it and prepare your environment.

Prerequisites

Before setting up the AEM SDK locally, make sure you have the following installed:

  • Java 11 (LTS) → Required to run AEM SDK.
  • Node.js (v14.x) → Needed for frontend build tools and AEM project UI components.
  • npm (v6.x) → Comes with Node.js, used to install and manage frontend dependencies.

You will see two folders here: author on port 4502 and publish on port 4503. Each one has its own JAR and license file so you can fire up a local AEM setup.

~/aem-sdk
├── author
│   ├── aem-author-p4502.jar
│   └── license.properties
└── publish
    ├── aem-publish-p4503.jar
    └── license.properties

Both the author and publish folders now come with everything you need — the JAR file, license, a debug start script, and the crx-quickstart directory where AEM stores its configs and content. With this setup, you’re ready to spin up local AEM instances just like in a real environment.

~/aem-sdk
├── author
│   ├── aem-author-p4502.jar
│   ├── license.properties
│   ├── start-debug.bat
│   └── crx-quickstart
│
├── publish
│   ├── aem-publish-p4503.jar
│   ├── license.properties
│   ├── start-debug.bat
│   └── crx-quickstart

Running these commands will spin up your local AEM instances — Author on port 4502 and Publish on port 4503. Once the startup logs finish scrolling by, you can jump into your browser and hit http://localhost:4502 for Author or http://localhost:4503 for Publish.

java -jar aem-author-p4502.jar
java -jar aem-publish-p4503.jar

After running the JAR, you’ll see the AEM Quickstart launch screen pop up (like in the screenshot below). This confirms your Author instance has started successfully on http://localhost:4502, while the Publish instance will be available on http://localhost:4503

» Author Mode (Port 4502)

» Publish Mode (Port 4503)

When Quickstart is done, the browser opens up the AEM login screen (screenshot below). Here you can sign in to the Author environment at http://localhost:4502 with the default admin credentials and start working.

Using the default credentials (admin / admin), sign in through the login screen to access the Author environment.
Once authenticated, you will be taken to the AEM authoring interface (shown below), where you can navigate to modules like Sites, Assets, Projects, and more to create, edit, and manage your content.

Setting Up Remote JVM Debugging for AEM

While IntelliJ IDEA is commonly used for setting up Remote JVM Debug configurations (as shown in the screenshot below), you’re free to use any IDE or tool that supports remote debugging.

With the configuration in place, you can name your debug profile (e.g., AEM Debug), set the debugger mode to Attach to remote JVM, and specify the host as localhost with port 8000. 

-agentlib:jdwp=transport=dt_socket,server=y,suspend=n,address=*:8000

Explanation of each option:

  • address=*:8000 → binds the debug server to port 8000 (accessible from localhost or remote depending on setup).
  • transport=dt_socket → uses socket transport for communication.
  • server=y → tells the JVM to act as a debug server waiting for a debugger to connect.
  • suspend=n → JVM won’t pause at startup; it runs normally and waits for the debugger to attach.

Once this setup is saved, you will be able to connect IntelliJ to your running AEM instance and step through the code during execution.

If port 8000 is already occupied by another process, your debugger won’t be able to attach. To verify this, run the following command in your terminal or command prompt:
netstat -ano | findstr "8000"

This will display any processes currently using port 8000. If you find a conflicting process, note its PID (Process ID) from the output, then terminate it with:

taskkill /F /PID <pid>

With the port freed up, you’re ready to dive back into your local AEM setup. Inside the ~/aem-sdk folder, you will find the full directory structure for both Author and Publish instances.

~/aem-sdk
├── author
│   ├── aem-author-p4502.jar
│   ├── license.properties
│   ├── start-debug.bat
│   ├── crx-quickstart
│   └── publish
│       ├── aem-publish-p4503.jar
│       ├── start-debug.bat
│       └── crx-quickstart
│
└── publish
    ├── aem-publish-p4503.jar
    ├── license.properties
    └── crx-quickstart

In the ~/aem-sdk folder, you will also find some handy scripts to kick off AEM in debug mode. For example, check out author/start-debug.bat — it is just a little batch file that fires up the Author instance with debugging turned on:

» author/start-debug.bat

cd C:\aem-sdk\author
C:
java -Xmx2048m -XX:PermSize=256m -XX:MaxPermSize=512m -agentlib:jdwp=transport=dt_socket,address=8000,server=y,suspend=n -jar aem-author-p4502.jar -v
pause

» author/publish/start-debug.bat

cd C:\aem-sdk\publish
C:
java -Xmx2048m -XX:PermSize=256m -XX:MaxPermSize=512m ^
-agentlib:jdwp=transport=dt_socket,address=8000,server=y,suspend=n ^
-jar aem-publish-p4503.jar -v
pause

If you would like to use a port other than 8000, just update the value in your start-debug.bat file and make sure the Remote JVM Debug configuration in IntelliJ matches that port.

Instead of launching AEM directly with the aem-author-p4502.jar or aem-publish-p4503.jar, you will run the start-debug.bat script. This ensures AEM starts up with debugging enabled.

Once AEM is running, flip over to IntelliJ and select your AEM Debug configuration (as shown in the screenshot below). Hit the debug button, and IntelliJ will attach to the running AEM instance, letting you step through code, set breakpoints, and inspect variables in real time.

Configuring your Replication Agents

You can access the Replication Agents console in AEM Author directly at:

http://localhost:4502/etc/replication/agents.author.html

Opening the Replication Agents console at http://localhost:4502/etc/replication/agents.author.html shows the predefined agents on Author:

  • Default Agent (publish) – Replicates to the default Publish instance.
  • Dispatcher Flush (flush) – Sends cache flush requests (disabled by default).
  • Reverse Replication Agent – Pulls content back from Publish (usually disabled).
  • Static Agent – Writes a static file-based copy of content.
  • Test and Target – Used for Adobe Target integrations.
Once you click into the Default Agent (publish), you’ll see its detailed configuration screen (as shown below).
From here you can adjust core settings such as enabling/disabling the agent, defining the replication endpoint (in this case http://localhost:4503), setting the serialization type, and configuring credentials.
The replication endpoint is defined with the full servlet URL:
http://localhost:4503/bin/receive?sling:authRequestLogin=1

This is the receiver servlet on the Publish instance. It accepts replicated content from Author and requires authentication (sling:authRequestLogin=1) to ensure that only authorized agents can push content.
In most cases, the Agent User ID configured in the replication agent (e.g., admin in local setups) is used to authenticate against this endpoint.

Run Replication Test against the Publish endpoint (http://localhost:4503/bin/receive?sling:authRequestLogin=1). A successful result ends with Replication test succeeded, confirming that Author can deliver content to Publish.

Choosing the Right Path

AEM offers several ways to build a site—the right choice depends on your goals and your team’s skills. In practice, most projects follow one of two approaches:

  • AEM Project Archetype (Maven multi-module). Best when you expect heavy customization or are working on AEM 6.5 or Cloud Service with full dev workflows. It generates a standard project (modules like core, ui.apps, ui.content, ui.frontend, dispatcher, and all) and shows how Core Components are included. Experience League
  • AEM Site Templates (Quick Site Creation). A low-code path for Cloud Service: spin up a site quickly with out-of-the-box components and theme it with CSS/JS. Great for fast starts and newer teams. Experience League

Note: Adobe now recommends exploring Edge Delivery Services for brand-new builds, but both approaches above remain valid—choose based on customization needs, timeline, and team skills.

» AEM Project Archetype

AEM as a Cloud Service

mvn -B org.apache.maven.plugins:maven-archetype-plugin:3.4.0:generate \
  -D archetypeGroupId=com.adobe.aem \
  -D archetypeArtifactId=aem-project-archetype \
  -D archetypeVersion=54 \
  -D appTitle="FLAGTICK" \
  -D appId="flagtick" \
  -D groupId="com.flagtick" \
  -D aemVersion=cloud \
  -D singleCountry=n

AEM 6.5 (AMS/on-prem)

Match the exact service pack you run; Adobe lists 6.5.17.0+ as the supported baseline for recent archetype releases.

mvn -B org.apache.maven.plugins:maven-archetype-plugin:3.4.0:generate \
  -D archetypeGroupId=com.adobe.aem \
  -D archetypeArtifactId=aem-project-archetype \
  -D archetypeVersion=54 \
  -D appTitle="FLAGTICK" \
  -D appId="flagtick" \
  -D groupId="com.flagtick" \
  -D aemVersion=6.5.17.0 \
  -D singleCountry=n

AEM Project Archetype — resources & support

If you choose the AEM Project Archetype path, the generator scaffolds a Cloud Manager–ready, multi-module workspace—the layout you see below.

└── flagtick
    ├── LICENSE
    ├── README.md
    ├── all
    ├── archetype.properties
    ├── core
    ├── dispatcher
    ├── it.tests
    ├── pom.xml
    ├── ui.apps
    ├── ui.apps.structure
    ├── ui.config
    ├── ui.content
    ├── ui.frontend
    └── ui.tests

From the project root, run mvn clean install to build all modules, run tests, and produce the aggregated all package.

[INFO] ------------------------------------------------------------------------
[INFO] Reactor Summary:
[INFO] 
[INFO] FLAGTICK 1.0.0-SNAPSHOT ............................ SUCCESS [  0.587 s]
[INFO] FLAGTICK - Core 1.0.0-SNAPSHOT ..................... SUCCESS [ 11.070 s]
[INFO] FLAGTICK - UI Frontend 1.0.0-SNAPSHOT .............. SUCCESS [ 22.347 s]
[INFO] FLAGTICK - Repository Structure Package 1.0.0-SNAPSHOT SUCCESS [  0.914 s]
[INFO] FLAGTICK - UI apps 1.0.0-SNAPSHOT .................. SUCCESS [  6.445 s]
[INFO] FLAGTICK - UI content 1.0.0-SNAPSHOT ............... SUCCESS [  2.236 s]
[INFO] FLAGTICK - UI config 1.0.0-SNAPSHOT ................ SUCCESS [  0.564 s]
[INFO] FLAGTICK - All 1.0.0-SNAPSHOT ...................... SUCCESS [ 12.418 s]
[INFO] FLAGTICK - Integration Tests 1.0.0-SNAPSHOT ........ SUCCESS [  7.096 s]
[INFO] FLAGTICK - Dispatcher 1.0.0-SNAPSHOT ............... SUCCESS [  0.102 s]
[INFO] com.adobe.cq.cloud.testing.ui.cypress - UI Tests 0.0.1-SNAPSHOT SUCCESS [ 13.155 s]
[INFO] ------------------------------------------------------------------------
[INFO] BUILD SUCCESS
[INFO] ------------------------------------------------------------------------
[INFO] Total time:  01:19 min
[INFO] Finished at: 2025-09-20T22:52:40+07:00
[INFO] ------------------------------------------------------------------------

Then, to deploy locally, run mvn clean install -PautoInstallSinglePackage—it builds and installs the aggregated all package to your local Author (http://localhost:4502 by default).

[INFO] ------------------------------------------------------------------------
[INFO] Reactor Summary:
[INFO] 
[INFO] FLAGTICK 1.0.0-SNAPSHOT ............................ SUCCESS [  0.610 s]
[INFO] FLAGTICK - Core 1.0.0-SNAPSHOT ..................... SUCCESS [  9.139 s]
[INFO] FLAGTICK - UI Frontend 1.0.0-SNAPSHOT .............. SUCCESS [ 19.393 s]
[INFO] FLAGTICK - Repository Structure Package 1.0.0-SNAPSHOT SUCCESS [  2.908 s]
[INFO] FLAGTICK - UI apps 1.0.0-SNAPSHOT .................. SUCCESS [  5.717 s]
[INFO] FLAGTICK - UI content 1.0.0-SNAPSHOT ............... SUCCESS [  0.527 s]
[INFO] FLAGTICK - UI config 1.0.0-SNAPSHOT ................ SUCCESS [  0.221 s]
[INFO] FLAGTICK - All 1.0.0-SNAPSHOT ...................... SUCCESS [ 13.760 s]
[INFO] FLAGTICK - Integration Tests 1.0.0-SNAPSHOT ........ SUCCESS [  8.985 s]
[INFO] FLAGTICK - Dispatcher 1.0.0-SNAPSHOT ............... SUCCESS [  0.245 s]
[INFO] com.adobe.cq.cloud.testing.ui.cypress - UI Tests 0.0.1-SNAPSHOT SUCCESS [ 11.181 s]
[INFO] ------------------------------------------------------------------------
[INFO] BUILD SUCCESS
[INFO] ------------------------------------------------------------------------
[INFO] Total time:  01:15 min
[INFO] Finished at: 2025-09-20T23:03:21+07:00
[INFO] ------------------------------------------------------------------------

Next, open Package Manager at http://localhost:4502/crx/packmgr/index.jsp and verify packages are installed and version-aligned.

Note: Blank pages usually mean a missing/mismatched dependency—for example, ui.content installed without the matching ui.apps. If ui.content shows a red Requires, install the required package (typically ui.apps) before opening pages.

Navigate to the Sites console at http://localhost:4502/sites.html/content.
You should see the FLAGTICK site, with a standard structure that includes Language Masters and United States (US)branches. This hierarchy is generated by the archetype based on your language/country and singleCountry settings.

Open the US → EN homepage: http://localhost:4502/editor.html/content/flagtick/us/en.html.
You should see the FLAGTICK header, sample tiles, and Hello World;

» AEM Site Templates

Note: Site Templates are available on AEM as a Cloud Service (and the Cloud SDK). If you’re on AEM 6.5, use the Project Archetype approach—there’s no Site Templates console on 6.5.

Here’s a longer wrap-up you can drop in as the article’s conclusion, with a clean hand-off to the Dispatcher piece:

Wrapping up

You now have a local AEM SDK with a Cloud-ready project from the AEM Project Archetype. You built (mvn clean install), installed locally (-PautoInstallSinglePackage), verified in Package Manager, and confirmed the site in Sites/Page Editor. Blank pages? Check install order, version mismatches, and that bundles are Active. Rule of thumb: use Cloud Manager for code; Package Manager for content-only packages.

Side note: Site Templates are a Cloud feature. If you’re on 6.5 locally, stick with the Archetype path covered here.

What’s next

In the next part, we’ll focus on the Dispatcher—AEM’s cache and security gate in front of Publish. You’ll:

  • Understand the folder structure and how vhosts, farms, filters, and cache rules fit together.
  • Run Dispatcher in Docker locally, mirroring Cloud Manager validation.
  • Point a host (e.g., flagtick.local) at your container, exercise cache/invalidation, and inspect logs.
  • Apply a few production-grade defaults (clientlib caching, header rules, deny/allow filters).

Prereqs for the next article

  • Docker Desktop installed.
  • AEM Publish running locally (e.g., http://localhost:4503).
  • The Adobe Dispatcher Tools/SDK or AMS Dispatcher Docker image available.
  • A hosts entry for your test domain (e.g., 127.0.0.1 flagtick.local).

When you are ready, jump to: “Validate AEM Dispatcher Config Like Cloud Manager”.