A working AEMaaCS setup has three parts, and each one catches different mistakes. The AEM SDK runs a local author and publish on your machine, so you can build and test bundles, components and content. The Dispatcher SDK validates your caching and filter rules against the same Apache configuration the cloud uses. The aio CLI with the RDE plugin connects you to a Rapid Development Environment, a cloud author where you can sync and debug code without waiting for a full pipeline.

This post walks through all three in order: check Java and Maven, download the SDK, start the local quickstart, scaffold a project, validate its Dispatcher configuration, and connect the aio CLI to an RDE. Each step ends with a check, so you know it worked before you move on.

Table of contents

• Why this matters
• Who should read this
• Prerequisites
• The three tools and what each one is for
• Hands-on: set up the environment step by step
• Local SDK, Dispatcher SDK and RDE compared
• Common mistakes and troubleshooting
• Hands-on challenge
• Key takeaways
• Knowledge check
• Frequently asked questions
• Continue your learning

Why this matters

Teams that skip local setup find out about problems late. A Maven build that compiles on a laptop with the wrong JDK, a filter rule that the Dispatcher rejects, or an OSGi config that does not resolve will each cost a full pipeline run to discover. With the local SDK and the Dispatcher validator, most of those failures show up in minutes.

The RDE is the second half of the picture. It is the cloud environment where your code runs with the real author and Dispatcher, and it is where you debug problems that only appear in the cloud.

Who should read this

This is for developers starting on an AEMaaCS program, and for anyone who has a local AEM 6.5 setup and needs to move to the SDK. You should be comfortable on a terminal and have used Maven before.

Prerequisites

• Lesson 01, AEM as a Cloud Service Overview for Developers, for the terms program, environment and RDE.
• A Java 21 JDK. Adobe’s local setup guide uses Java 21 for the AEM SDK. The JDK that Cloud Manager builds with is set separately, by the .cloudmanager/java-version file in your project.
• Maven 3.9 or later, Node.js 20 or later (the current aio CLI needs at least 20.17), and Docker Desktop for the Dispatcher validator.
• Access to an AEMaaCS program in Adobe Cloud Manager with a Developer role, and an RDE provisioned for it. Ask your program admin if you do not have one.
• Access to the Software Distribution portal, where the AEM SDK and Dispatcher tools are downloaded.

The three tools and what each one is for

Each tool answers a different question. Keep them separate in your head, because each one has its own install path and its own failure modes.

• AEM SDK quickstart: a local author and publish, started from a single jar. Use it to build and test bundles and content on your machine.
• Dispatcher SDK (Adobe calls it Dispatcher Tools): a set of scripts and a Docker image that validate your Dispatcher source and run Apache with the Dispatcher module locally.
• aio CLI with the RDE plugin: connects your terminal to a Rapid Development Environment, so you can install code and read logs there.

Hands-on: set up the environment step by step

Step 1: Check Java and Maven

Confirm that the right Java version is on your path before you download anything. The SDK jar and the Maven build both depend on it.

java -version
mvn -version
node -v
docker --version

The first line of the Java output should show version 21. If it shows an older version, set JAVA_HOME to a JDK 21 installation and open a new terminal before you continue. Check that mvn -version reports the same Java home, because Maven uses JAVA_HOME rather than the first java on your path.

Step 2: Download the AEM SDK and unpack the Dispatcher Tools

Sign in to the Software Distribution portal at experience.adobe.com/#/downloads, open the AEM as a Cloud Service tab and download the latest AEM SDK. Pick the version that matches your production environment, which you can see in Cloud Manager or in the About dialog on your cloud author. It is one zip file. It contains the quickstart jar and the Dispatcher Tools: a shell installer for macOS and Linux, and a zip for Windows.

Unzip the SDK, then run the Dispatcher Tools installer inside a folder of its own. It creates a dispatcher-sdk-<version> folder with the bin scripts used later in this lesson. On Windows, unzip aem-sdk-dispatcher-tools-<version>-windows.zip into the same folder instead.

cd ~/Downloads && unzip aem-sdk-<version>.zip -d aem-sdk-<version>
mkdir -p ~/aem-sdk/dispatcher && cd ~/aem-sdk/dispatcher
cp ~/Downloads/aem-sdk-<version>/aem-sdk-dispatcher-tools-<version>-unix.sh .
chmod a+x aem-sdk-dispatcher-tools-<version>-unix.sh
./aem-sdk-dispatcher-tools-<version>-unix.sh

Step 3: Start the local quickstart

Create a folder for the SDK outside your project, so the quickstart jar and its generated files do not end up in Git. Then start the author instance in development mode.

mkdir -p ~/aem-sdk/author
cp ~/Downloads/aem-sdk-<version>/aem-sdk-quickstart-<version>.jar ~/aem-sdk/author/aem-author-p4502.jar
cd ~/aem-sdk/author
java -jar aem-author-p4502.jar

The file name sets the run mode and the port: aem-author-p4502.jar starts an author on port 4502. On the first start the quickstart asks for an admin password. Any value works, but Adobe recommends admin for local instances so you do not have to reconfigure tools. The first start unpacks the repository and takes several minutes. When the console prints Quickstart started, open http://localhost:4502 and sign in. Start the jar from a terminal; it does not start by double-clicking.

Note:- For a local publish instance, copy the same jar to ~/aem-sdk/publish/aem-publish-p4503.jar and start it the same way. The file name gives it the publish run mode and port 4503, so the two instances do not clash.

Step 4: Scaffold a project with the archetype

Generate a project from the AEM project archetype. The example below creates a project named mysite with the package root com.mysite. The aemVersion=cloud property selects the AEMaaCS build.

mvn -B org.apache.maven.plugins:maven-archetype-plugin:3.3.1:generate \
  -D archetypeGroupId=com.adobe.aem \
  -D archetypeArtifactId=aem-project-archetype \
  -D archetypeVersion=58 \
  -D appTitle="My Site" \
  -D appId="mysite" \
  -D groupId="com.mysite" \
  -D aemVersion=cloud
cd mysite
mvn clean install

The build produces the core bundle, the UI packages and the Dispatcher source. Check that the build ends in BUILD SUCCESS. Then open the generated core module and confirm that its Maven dependency on the AEM SDK API uses the provided scope, with a version that matches your AEM version. To install the build on the local author started in Step 3, run mvn clean install -PautoInstallSinglePackage.

<dependency>
  <groupId>com.adobe.aem</groupId>
  <artifactId>aem-sdk-api</artifactId>
  <version><!-- must match the AEM version shown in the About dialog --></version>
  <scope>provided</scope>
</dependency>

Step 5: Validate the Dispatcher source

Start Docker Desktop, then run the validator from the Dispatcher Tools on the dispatcher/src folder of the project you just generated. It runs three phases: the rules check, an Apache syntax check in Docker, and an immutability check against the Adobe-managed files.

cd ~/projects/mysite
~/aem-sdk/dispatcher/dispatcher-sdk-<version>/bin/validate.sh dispatcher/src

To run the Dispatcher against a local publish instance, use the docker run script. The arguments are the source folder, the publish host and port, and the local port to listen on. Port 4503 is the publish port set by the aem-publish-p4503.jar file name. Docker reaches your machine through host.docker.internal. When it starts, open http://localhost:8080 to request pages through the local Dispatcher.

~/aem-sdk/dispatcher/dispatcher-sdk-<version>/bin/docker_run.sh dispatcher/src host.docker.internal:4503 8080

Note:- Paths in the commands above are examples. Adjust ~/aem-sdk/dispatcher/dispatcher-sdk-<version> and ~/projects/mysite to match where you unpacked the Dispatcher Tools and created the project.

Step 6: Install the aio CLI and the RDE plugin

Install the aio CLI globally, add the RDE plugin, and sign in to Adobe with the account that has access to your program.

npm install -g @adobe/aio-cli
aio plugins:install @adobe/aio-cli-plugin-aem-rde
aio login

Step 7: Connect the CLI to your RDE

Run the setup command and enter your organization, program and environment IDs when prompted. The example program is 12345 and the RDE environment is 67890. The command lists the programs and RDEs you can access, and selects them automatically when there is only one. It also asks whether to store the configuration locally, in a .aio file in the current folder. Local storage is recommended when you work with more than one RDE.

aio aem:rde:setup
aio aem:rde:setup --show
aio aem:rde:status

The --show flag displays the current configuration, so you can confirm the IDs before you install anything. aio aem:rde:status confirms that the RDE is reachable and lists what is deployed.

In a script or CI job where nobody can answer the prompts, set the IDs directly instead. Add -l to store them in the local .aio file.

aio config:set -l cloudmanager_orgid <your-org-id>@AdobeOrg
aio config:set -l cloudmanager_programid 12345
aio config:set -l cloudmanager_environmentid 67890

You need the Cloud Manager Developer product profile on the program for these commands to work.

Step 8: Install your code on the RDE

Zip the Dispatcher configuration from the dispatcher/src folder, then install the Dispatcher zip and the all content package. Run the commands from the project root. An install goes to both author and publish on the RDE.

cd dispatcher/src && zip -y -r ../../dispatcher.zip . && cd ../..
aio aem:rde:install dispatcher.zip
aio aem:rde:install all/target/<your-all-package>.zip
aio aem:rde:history
aio aem:rde:logs --target=author

Use aio aem:rde:history to confirm that the installs were recorded. Use aio aem:rde:logs when an install reports success but the feature does not work. Use --target=publish for the publish tier, and run aio aem:rde:logs --help for the other options, such as per-package log levels.

Local SDK, Dispatcher SDK and RDE compared

Common mistakes and troubleshooting

Hands-on challenge

Set up the environment on your own machine, using a program and environment you have access to. Then make one small change: add a new Sling Model in the core module, build it, and install the result on the RDE. Record the commands you ran, the environment ID and the output of aio aem:rde:history. If any step fails, write down the exact error message and the step that produced it.

Key takeaways

✅ Check Java and Maven before you install anything. Java 21 is the target.
✅ The quickstart runs a local author and publish. The jar file name sets the run mode and port, for example aem-author-p4502.jar.
✅ Validate the Dispatcher with the SDK before you push, so filter errors do not reach the pipeline.
✅ Use the archetype to scaffold a project, and keep the AEM SDK API version in step with your AEM version.
✅ Connect the aio CLI with the program and environment IDs. Check them with --show before you install.

Knowledge check

Frequently asked questions

Continue your learning

• Previous lesson: Lesson 03, AEMaaCS Architecture: Author, Publish, Dispatcher, CDN and Cloud Manager.
• Next lesson: Lesson 05, AEM Project Archetype and Repository Structure for AEMaaCS (unpublished draft; see the roadmap).
• Practice quiz: AEM Cloud Service practice test 1.
• Background on Dispatcher setup for AEM 6.x: Set up Dispatcher in AEM.
• Roadmap: AEM as a Cloud Service learning roadmap.