Adobe Experience Manager (AEM) as a Cloud Service SDK evolves frequently — each release introduces new tools, Dispatcher versions, and folder structures.
This guide walks you through setting up the latest AEM SDK (v2025.x) on macOS/Windows, configuring Author + Publish instances, and validating Dispatcher locally — ensuring full parity with Cloud Manager pipelines.

Setting Up Your Local AEM Development Environment

Before setting up your local AEM environment, make sure you have access to an Adobe Experience Cloud account that is linked to your organization’s program.

This connection gives you access to the Software Distribution portal, where you’ll download the latest AEM SDK (Author + Publish + Dispatcher Tools).

💡 My account is associated with Adobe’s client program “Flagtick”, which provides AEM cloud services access. This ensures I can securely download and test AEM SDK builds that match our Cloud Manager setup.

Once your account is linked, visit the Software Distribution Portal to download the AEM SDK.
Use filters to choose:

• Software Type: Tooling
• Operating System: Your local OS

📦 Adobe updates the SDK monthly — always match the SDK version with your Cloud Manager runtime.

Always download the latest AEM SDK version to ensure you are working with the newest features and fixes. Older builds are also available if your project requires version 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.

Once extracted, the SDK folder contains everything required to start your local AEM instance.

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.

Your SDK includes two runnable folders — _{^{author (4502)}} and _{^{publish (4503)}} — each with its own JAR and license file.

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

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

You can start your AEM SDK instances (Author and Publish) directly from the terminal using the provided scripts or _{^{java -jar}} commands.

💻 On macOS / Linux

Navigate to the extracted SDK folder and run:

cd ~/aem-sdk/author
sh aem-author-http.command

cd ~/aem-sdk/author
sh aem-author-http.command

Then start the Publish instance:

cd ~/aem-sdk/publish
sh aem-publish-http.command

cd ~/aem-sdk/publish
sh aem-publish-http.command

🪟 On Windows

Double-click the _^.bat file (for example, _{^{start-author.bat}}) or run from Command Prompt:

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

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

Once the startup logs finish, open:

• http://localhost:4502 → Author instance
• http://localhost:4503 → Publish instance

» Author Mode (Port 4502)

» Publish Mode (Port 4503)

Once AEM Quickstart has finished loading, open your browser and go to http://localhost:4502 to access the Author environment.
Use the default admin credentials to sign in:

Username: admin
Password: admin

Username: admin
Password: admin

When Quickstart is done, the browser opens up the AEM login screen (screenshot below).

After logging in, you will be redirected to the AEM authoring interface (screenshot below), where you can manage Sites, Assets, and other modules.

💡 Once you can access this dashboard, your local AEM Author instance is up and running. You are now ready to import your project codebase or start developing custom components.

Enable Remote Debugging for AEM SDK (Optional Step)

Remote debugging lets you connect your IDE (like IntelliJ IDEA) to your AEM instance to inspect running code and diagnose issues.

You can use IntelliJ IDEA (as shown below) or any IDE that supports remote JVM debugging.

With the debug configuration created, name it something clear like AEM Debug, set the debugger mode to Attach to remote JVM, and configure:

• Host: _^localhost
• Port: _⁸⁰⁰⁰

Then, use the following JVM argument when starting AEM:

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

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

Parameter breakdown:

• _{^{address=*:8000}} — binds the debug server to port 8000
• _{^{transport=dt_socket}} — uses socket transport for debugging
• _^server=y — runs JVM as a debug server
• _^suspend=n — starts AEM normally while waiting for debugger to attach

Once configured, attach IntelliJ to your running AEM instance to step through code in real time.

netstat -ano | findstr "8000"

netstat -ano | findstr "8000"

This shows processes using port 8000. To terminate a conflicting one:

taskkill /F /PID <pid>

taskkill /F /PID <pid>

Once the port is free, navigate to your _^~/aem-sdk directory — this contains the startup and debug scripts 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

~/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

These scripts are preconfigured to launch your local AEM instances with JVM debugging enabled — ideal for remote debugging from IntelliJ or VS Code.

# Author
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

# Publish
cd C:\aem-sdk\publish
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

# Author
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

# Publish
cd C:\aem-sdk\publish
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

Once AEM is running, open IntelliJ and start your AEM Debug configuration — the IDE will automatically attach to the running instance. You can now step through code, inspect variables, and debug AEM in real time.

Configuring Replication Agents (Post-Setup)

Once both your Author and Publish instances are running, you can verify replication using the Replication Agents console.

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

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

The most relevant for local setup are:

• Default Agent (publish) – Replicates content from Author → Publish (port 4503).
• Dispatcher Flush (flush) – Sends cache-flush requests (disabled by default).

(Other agents like Reverse Replication, Static, and Adobe Target are for specific enterprise scenarios and remain disabled in local environments.)

Below is an example of the default publish agent configuration:

The replication endpoint is defined with the full servlet URL:

http://localhost:4503/bin/receive?sling:authRequestLogin=1

http://localhost:4503/bin/receive?sling:authRequestLogin=1

Below is the Default Agent configuration view in AEM, showing these settings:

The replication endpoint (_{^{/bin/receive?sling:authRequestLogin=1}}) is the receiver servlet on the Publish instance. It ensures that only authorized agents from the Author environment can replicate content.

In most local setups, the Agent User ID (e.g., admin) defined in the replication agent is used to authenticate against this endpoint.

Below is the Transport tab configuration showing the URI and credentials setup:

After configuring the Transport settings, you can verify that the Author instance successfully connects to the Publish endpoint by running a Replication Test.
Navigate to:

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

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

Below is an example of a successful replication test result:

Verifying Package Installation and Replication

After both AEM Author (4502) and Publish (4503) instances are running, it is important to confirm that your local environment can install and replicate packages properly.

http://localhost:4502/crx/packmgr/

http://localhost:4502/crx/packmgr/

Open the CRX Package Manager on Author and check that your site package (e.g., Flagtick Site) appears with status OK.
If not installed, upload and install it, then click Replicate to push it to the Publish instance.

Verify the same package exists under _{^{http://localhost:4503/crx/packmgr/}} with matching version and size.

From the Sites Console, navigate to your site root (e.g., _{^{/content/flagtick}}), then choose: Manage Publication → Publish now.

If replication doesn’t appear immediately on the Publish instance, you can verify the transfer logs from the Author side.

http://localhost:4502/etc/replication/agents.author/publish.log.html#end

http://localhost:4502/etc/replication/agents.author/publish.log.html#end

Open your Publish instance to confirm that the content has been delivered successfully:

http://localhost:4503/content/flagtick/us/en.html

http://localhost:4503/content/flagtick/us/en.html

If the page loads but looks blank or incomplete, it likely means only the page node (_{^{/content/flagtick/us/en}}) was activated — without its linked templates, components, or clientlibs.

To fix this cleanly, redeploy everything in one go by running:

mvn clean install -PautoInstallSinglePackagePublish

mvn clean install -PautoInstallSinglePackagePublish

Set Up Local HTTPS in AEM SDK

Using AEM’s SSL Configuration Console is the fastest way to enable HTTPS for your Author and Publish instances. You can either generate a self-signed certificate or import the official Adobe localhost certificate.

Navigate to: 👉 http://localhost:4502/libs/granite/security/content/sslConfig.html

If you are running both Author and Publish instances, configure HTTPS separately for each.

Add these entries to your _^/etc/hosts file so AEM can resolve your local HTTPS domains:

127.0.0.1 author.local
127.0.0.1 publish.local

127.0.0.1 author.local
127.0.0.1 publish.local

When you open the SSL Configuration Console, AEM will ask for credentials to create its Key Store and Trust Store.
You can use the same password for both fields unless your organization requires separate stores. (Eg: admin/admin)

Download Adobe’s ready-to-use localhost certificate package. It includes both the public certificate (_{^{localhost.crt}}) and private key (_{^{localhostprivate.der}}) that work directly with AEM’s SSL Configuration wizard.

👉 Use the SSL Configuration Wizard (Adobe Experience League)
Or download the ZIP directly:
Adobe localhost certificate.zip

Select Import Certificate, then upload the ^_.crt and ^_.der files from the package.
This approach keeps your setup aligned with Adobe’s demo and Cloud Manager environments.

Once the certificate and key files are uploaded, complete the SSL Connector section to define your HTTPS endpoint.

Enter your local hostname and port:

Once your hostname and port are set, click Next to let AEM create the HTTPS connector.
If everything is valid, you’ll see a confirmation message:

Use _^openssl to confirm the Common Name (CN) inside your certificate:

openssl s_client -connect author.local:5433 -servername author.local

openssl s_client -connect author.local:5433 -servername author.local

If the CN is _^localhost, use:

https://localhost:5433/

https://localhost:5433/

to avoid hostname mismatch warnings.

For the Publish instance (port 8443), the process is identical. However, HTTPS may take a minute or two to initialize after startup — this delay occurs while Jetty’s SSL connector is created internally.

If you run this too early:

openssl s_client -connect publish.local:8443 -servername publish.local

openssl s_client -connect publish.local:8443 -servername publish.local

the command may hang until the connector is active.
That is normal — AEM’s Granite Security service initializes SSL after all bundles are loaded.

Once configured, you can securely access both instances:

• Author → https://author.local:5433/
• Publish → https://publish.local:8443/

If the browser shows a certificate warning, trust the certificate in your OS (Keychain on macOS or Trusted Root on Windows).

If you ever need to turn off HTTPS temporarily:

1. Open the AEM OSGi Console → http://localhost:4503/system/console/bundles
2. In the search bar, type Adobe Granite SSL Context Factory for Jetty
3. Click Stop on that bundle

Once stopped, AEM will shut down its HTTPS connector and automatically fall back to HTTP mode (e.g., http://localhost:4503).

What’s next

In the next part, we will move on to the Dispatcher — AEM’s cache and security layer sitting in front of the Publish instance. You will:

• Understand the Dispatcher folder structure and how vhosts, farms, filters, and cache rules work together.
• Run Dispatcher in Docker locally to mirror Adobe Cloud Manager validation.
• Map a local domain (_{^{e.g. flagtick.local}}) to your container and test caching, invalidation, and request logs.
• Apply a few production-grade best practices like clientlib caching, header rules, and deny/allow filters.

Before You Start

Make sure you have:

• Docker Desktop installed and running.
• AEM Publish instance active (e.g. http://localhost:4503).
• The Adobe Dispatcher SDK or AMS Dispatcher Docker image downloaded.
• A hosts entry for your test domain (_{^{e.g. 127.0.0.1 flagtick.local}}).

👉 When you’re ready, continue to: Validate AEM Dispatcher Config Like Cloud Manager