DEV Community

Cover image for Running AEM Without Losing Your Mind: A Practical Local & AWS EC2 Setup Guide
Venkata Pavan Vishnu Rachapudi
Venkata Pavan Vishnu Rachapudi Subscriber

Posted on

Running AEM Without Losing Your Mind: A Practical Local & AWS EC2 Setup Guide

#aws #aem #adobe #programming

I still remember the first time I tried setting up AEM locally — the JAR started, the logs kept scrolling, the fan noise increased, and for a good 10 minutes I wasn’t sure whether AEM was actually starting or silently failing.

If you’ve worked with AEM long enough, you know this feeling.

Adobe Experience Manager isn’t a tool you just install. It’s a platform — built on Java, OSGi, Sling, and a JCR-backed repository — and the learning curve usually starts the moment you try to run it on your machine.

In real projects, getting AEM running reliably (locally and on AWS) is more important than writing your first component. If your setup is unstable, everything else breaks — debugging, component development, deployments, and even confidence.

This guide is based on how I actually set up AEM in day-to-day work — starting locally, understanding what’s happening under the hood, and then moving the same setup to an AWS EC2 instance before thinking about production or AEM as a Cloud Service.

This blog walks you through:

  • Local AEM setup using Java JAR and Docker
  • Understanding run modes and debugging
  • Deploying AEM on AWS EC2
  • Core AEM consoles: CRXDE Lite, Package Manager, and OSGi System Console

What CRX Actually Is (And Why You’ll Keep Hearing About It)

One of the first things you’ll hear in AEM projects is “check it in CRX” or “look at the node structure”.

CRX stands for Content Repository eXtreme.

Think of CRX as the heart of AEM. Everything — pages, components, dialogs, permissions, configurations — ends up here in some form. Under the hood, modern AEM uses Apache Jackrabbit Oak, which is Adobe’s scalable implementation of the Java Content Repository (JCR) standard.

If you understand CRX at a basic level, debugging AEM becomes much easier. If you don’t, AEM often feels like a black box.

Running AEM Locally Using the Quickstart JAR

This is still the most straightforward way to run AEM — and honestly, the one I recommend when you’re learning or debugging something tricky.

Before You Start

Make sure you have:

  • Java 11 or 17 (depending on your AEM version)
  • At least 8 GB RAM on your machine
  • AEM SDK Quickstart JAR downloaded from Adobe

AEM is heavy. If your laptop struggles here, it will struggle everywhere.

Folder Setup (Keep It Simple)

I always keep author and publish separate. It avoids confusion later.

aem-author/
aem-publish/
Enter fullscreen mode Exit fullscreen mode

Drop the same aem-sdk-quickstart.jar into both folders.

Starting the Author Instance 

java -Xmx4g -jar aem-sdk-quickstart.jar -r author,local
Enter fullscreen mode Exit fullscreen mode

The first startup is slow. Don’t panic. Grab coffee.

Once it’s done:

Starting the Publish Instance

After the first run, AEM generates startup scripts under crx-quickstart/bin.

Edit the start script and change the port:

CQ_PORT=4503
Enter fullscreen mode Exit fullscreen mode

Then run with:

java -Xmx4g -jar aem-sdk-quickstart.jar -r publish,local
Enter fullscreen mode Exit fullscreen mode

This separation pays off later when you debug author vs publish issues.

Running AEM with Docker (When You Want Consistency)

Docker makes sense when:

  • Multiple developers need the same setup
  • You want to avoid “works on my machine” issues
  • You’re closer to cloud-style deployments

For pure learning, JAR is fine. For teams, Docker helps.

Basic Folder Layout 

aem/
 ├── author/
 │   └── Dockerfile
 ├── publish/
 │   └── Dockerfile
 ├── aem-sdk-quickstart.jar
 └── license.properties
Enter fullscreen mode Exit fullscreen mode

A Simple Author Dockerfile

Keep it readable. Avoid over-optimizing early.

FROM eclipse-temurin:11-jdk

# AEM directories
ENV AEM_HOME=/opt/aem
ENV AEM_RUNMODE=author

# Create AEM home
RUN mkdir -p ${AEM_HOME}
WORKDIR ${AEM_HOME}

# Copy AEM Quickstart and license
COPY aem-author-p4502.jar aem.jar
#COPY license.properties license.properties

# JVM tuning (safe for local testing)
ENV JAVA_OPTS="-Xms1024m -Xmx2048m -XX:+UseG1GC"

# Expose AEM + Debug ports
EXPOSE 4502 58242

# Persist important data
VOLUME [  "/opt/aem/crx-quickstart/repository",  "/opt/aem/crx-quickstart/logs", "/opt/aem/backup"]

# Start AEM Author
CMD java $JAVA_OPTS -jar aem.jar \
  -r ${AEM_RUNMODE} \
  -Dcrx.quickstart.server.port=4502 \
  -Dcrx.quickstart.nodename=author
Enter fullscreen mode Exit fullscreen mode

Build and Run 

docker build -t aem-author -f author/Dockerfile .
docker run -d -p 4502:4502 -p 5005:5005 aem-author
Enter fullscreen mode Exit fullscreen mode

Repeat the same idea for Publish on port 4503.

Run Modes: Small Flags, Big Impact

Run modes decide how AEM behaves. Misconfigured run modes are a common reason for “it works locally but not elsewhere” problems.

Common Ones You’ll Actually Use

  • author – where editors work
  • publish – where content is served
  • local – your machine
  • dev – developer-only configs
  • nosamplecontent – clean setup

How I Usually Set Them

Java:

-Dsling.run.modes=author,local,dev
Enter fullscreen mode Exit fullscreen mode

Docker:

-r author-local,docker
Enter fullscreen mode Exit fullscreen mode

Avoid dots in Docker run modes — it causes subtle issues.

Verify What’s Active 

http://localhost:4502/system/console/status-slingsettings
Enter fullscreen mode Exit fullscreen mode

If run modes are wrong, stop and fix them early.

Debugging AEM (Yes, You Can Debug It Like Any Java App)

AEM debugging feels intimidating until you realize it’s just a Java process.

Enable Debug Port 

-agentlib:jdwp=transport=dt_socket,server=y,suspend=n,address=*:5005
Enter fullscreen mode Exit fullscreen mode

Expose port 5005 if you’re using Docker.

Attach Your IDE

  • IntelliJ or VS Code
  • Host: localhost
  • Port: 5005

This is where AEM starts making sense — Sling Models, services, servlets, all debuggable.

Logs You’ll Check Daily 

crx-quickstart/logs/error.log
Enter fullscreen mode Exit fullscreen mode

If something breaks, this file almost always tells you why.

The Three AEM Consoles You’ll Live In

If you’re new to AEM, bookmark these URLs.

CRXDE Lite (/crx/de)

Used for:

  • Inspecting repository structure
  • Understanding how components are stored
  • Quick debugging

Rule of thumb: debug here, don’t build here.

Package Manager (/crx/packmgr)

This is how code and content move between environments.

  • Upload packages
  • Install builds
  • Deploy Maven outputs

In real projects, almost everything flows through Package Manager.

OSGi System Console (/system/console)

This is AEM’s engine room.

You’ll use it to:

  • Check bundles
  • Configure services
  • Troubleshoot weird issues

If AEM feels broken, this is the first place to look.

2. Package Manager (/crx/packmgr)

URL:

http://localhost:4502/crx/packmgr
Enter fullscreen mode Exit fullscreen mode

Used for:

  • Uploading content and code packages
  • Installing component bundles
  • Deploying builds from Maven

Typical usage:

mvn clean install -PautoInstallPackage
Enter fullscreen mode Exit fullscreen mode

3. OSGi System Console (/system/console)

URL:

http://localhost:4502/system/console
Enter fullscreen mode Exit fullscreen mode

Critical for:

  • Managing OSGi bundles
  • Configuring services (/configMgr)
  • Viewing Sling mappings
  • Checking logs and components health

Common sub-paths:

  • /system/console/bundles
  • /system/console/configMgr
  • /system/console/components

Running AEM on AWS EC2

When you move AEM from your laptop to EC2, the goal isn’t to make things fancy — it’s to make them predictable.

This setup works without constant memory pressure:

  • Instance type: t3.medium
  • RAM: 8 GB
  • Storage: 30 GB gp3
  • AMI: Amazon Linux 2023

Anything smaller and AEM startup becomes painful.

Step 1: Create the EC2 Instance

Go to EC2 → Launch instance

  • Choose Amazon Linux AMI
  • Select instance type t3.medium
  • Configure storage → set root volume to 30 GB gp3
  • Attach an IAM role (explained below)

Configure Security Group:

  • 4502 (Author) – restricted access
  • 4503 (Publish) – restricted access
  • 22 (SSH) – optional
  • 80 / 443 – if needed

🔒 For real environments, never expose 4502/4503 publicly.

Step 2: Access EC2 Without SSH Pain (Recommended)

The cleanest approach is Session Manager.

Attach an IAM role with:

  • AmazonSSMManagedInstanceCore

This gives you:

  • Browser-based shell
  • No SSH keys
  • No port 22 open
  • For most use cases, this is enough.

Step 3: Getting AEM SDK onto EC2 (Two Ways)

This is where people usually get confused.

Option 1: SCP Using SSH Keys (Old but Works)

If you already created a key pair:

scp -i my-key.pem aem-sdk-quickstart.jar ec2-user@<EC2-PUBLIC-IP>:/home/ec2-user/

Downsides:

  • Requires managing SSH keys
  • Requires port 22 open
  • Doesn’t scale well

Option 2: Upload to S3 and Pull from EC2 (Best Practice)

This is the cleaner and more cloud-native approach.

Steps:

  • Upload AEM SDK JAR to a private S3 bucket
  • Attach an IAM role to EC2 with:
  • s3:GetObject permission on that bucket
  • From EC2 (via Session Manager):

aws s3 cp s3://my-aem-artifacts/aem-sdk-quickstart.jar /home/ec2-user/

Why this is better:

  • No SSH keys
  • No SCP
  • Fully auditable
  • Easy to automate later

This is the approach I recommend.

We can use same commands we used during our local step. For Docker kind of setup we need docker installed on the EC2 Instance

AEM Components Overview

AEM components live under:

/apps/<project>/components
Enter fullscreen mode Exit fullscreen mode

Typical Component Structure 

my-component/
 ├── .content.xml
 ├── _cq_dialog/
 │   └── .content.xml
 ├── my-component.html
Enter fullscreen mode Exit fullscreen mode

Components are deployed as:

  • Maven-built OSGi bundles
  • Content packages via Package Manager

AEM Setup Pyramid

Below is how I personally visualize AEM setup and learning progression — from infrastructure to development and operations.

Practical AEM Flow (How I Recommend Working)

Final Words

If you understand:

  • How CRX (Content Repository eXtreme) works
  • Why Author ≠ Publish
  • How run modes control behavior
  • How /crx/de, /crx/packmgr, and /system/console fit together

👉 You’re already ahead of most beginners in AEM.

Master the fundamentals locally, automate everything with Maven, and only then think about scaling on AWS or Cloud Service.

Happy AEM engineering 🚀

Top comments (0)