Installing AEM Server Locally: A Complete Setup Guide

Introduction

Before you can write a single component or Sling Model, you need a running AEM instance to deploy against. For most developers, that means installing AEM On-Premise (also called AEM as a Jar, or "Classic") on their local machine. This article walks through everything you need to get a local AEM author instance running: licensing, the jar file itself, naming conventions, the folder structure it creates, the actual installation steps, the critical -gui flag, and how to apply service pack updates once you're running. It also covers how AEM Cloud Service differs from the jar-based installation, so you understand which flavor of AEM you're actually working with. After reading this, you'll be able to go from a blank machine to a working local AEM author instance, and you'll understand the on-prem vs. cloud distinction well enough to not get confused when a job description or project mentions "AEM as a Cloud Service." Prerequisites: Java installed (AEM 6.5 needs JDK 8 or 11; AEM Cloud SDK needs JDK 11), basic command-line comfort, and at least 8GB of free disk space / 4GB+ RAM to spare.

The Two Flavors of AEM: On-Premise vs. Cloud

Before installing anything, it's worth knowing that "AEM" today ships in two fundamentally different packaging models.

AEM On-Premise / AEM 6.5 (The Jar File)

• Distributed as a single executable .jar file

• You install it yourself on a server (or your laptop) that you manage

• Runs as a self-contained Java application with an embedded servlet engine

• Licensed per-instance with a license key or license properties file

• Upgrades are applied manually via Service Packs / Feature Packs

• This is what we're installing in this article

AEM as a Cloud Service (AEMaaCS)

• Not something you "install" the same way — it's a managed, containerized SaaS offering hosted by Adobe

• Local development uses the AEM SDK (aem-sdk-quickstart.jar), which simulates a Cloud Service author/publish instance locally for development and testing

• Continuous deployment model — Adobe pushes updates automatically, no manual Service Packs

• Uses Cloud Manager for CI/CD pipelines instead of manual bundle installs

• Repository structure is more restrictive (immutable /apps, mutable /content — enforced, not just convention)

• Licensing is subscription/entitlement-based through Adobe's cloud portal, not a license key file

Key distinction to remember: When someone says "I'm running AEM locally," they almost always mean one of two things — the classic 6.5 jar, or the Cloud Service SDK jar. Both are .jar files you run with java -jar, but they are different products with different update mechanisms, different licensing, and different repository constraints. This article focuses on the classic AEM 6.5 on-premise jar, since that's still the most common starting point for learning AEM fundamentals, but the installation mechanics (jar, run modes, ports, -gui flag) are conceptually similar for the Cloud SDK quickstart too.

Licensing: What You Need Before You Install

AEM is commercial software — you cannot legally run a production or even a serious development instance without a valid license.

How Licensing Works for AEM 6.5

1. License Key: Adobe provides a license key (a long alphanumeric string) tied to your organization's contract, or a trial license if you're evaluating

2. license.properties file: When you first launch AEM, it looks for this file in the install directory. If it's not present, AEM starts in an unlicensed evaluation mode (limited to 60 days / 500 activations for CQ5/AEM 6.x trial instances) and prompts you to enter a license key through the browser-based setup wizard

3. Trial/Developer Licenses: Adobe (through its partner/developer programs) distributes AEM trial jars pre-configured for 60-90 day evaluation. These still require accepting a license agreement on first run

Entering the License

When you access the instance for the first time at http://localhost:4502, if no license.properties exists, AEM shows a setup screen asking you to:

• Accept the Adobe license agreement

• Enter your license key (or continue with the time-limited unlicensed mode, if offered)

If you already have a license.properties file (often provided by your employer or training program), place it in the same directory as the jar file before the first run — AEM detects it automatically and skips the manual entry screen.

# Example license.properties structure (illustrative — real keys are provided by Adobe)
license.company=Your Company Name
license.downloadid=XXXXXXXXXXXXXXXXXXXXXXXX
license.customerid=XXXXXXXXXXXXXXXXXXXXXXXX
product.key=XXXX-XXXX-XXXX-XXXX-XXXX

Important: Never commit license.properties or real license keys to version control. Treat them like credentials.

Understanding the AEM Jar File

What the Jar Actually Is

The AEM quickstart jar (e.g., AEM_6.5_Quickstart.jar) is a self-extracting, self-running Java application. It bundles:

• An embedded Apache Felix OSGi container (the runtime AEM is built on)

• Apache Sling

• The Jackrabbit Oak content repository (JCR implementation)

• A default set of bundles, workflows, and the Granite/Touch UI

When you run it with java -jar, on first launch it unpacks itself into a working directory, creating the full runtime environment from a single compressed file.

Jar File Naming Conventions

Adobe names quickstart jars in a reasonably consistent pattern, and understanding it helps you avoid confusion when managing multiple instances:

AEM_6.5_Quickstart.jar

That's the file as downloaded — it doesn't yet encode run mode or port. Run mode and port are not baked into the jar filename by Adobe; instead, the convention of encoding them into the filename is a community/team best practice developers adopt when running multiple instances side by side, because AEM uses the jar's filename (minus extension) to determine default behavior in some setups, and more importantly, because it makes it immediately obvious what each jar instance is for when you have several sitting in different folders.

A common real-world naming convention looks like this:

cq-author-4502.jar
cq-publish-4503.jar

Or, including run mode explicitly:

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

Why this matters:

• author / publish — tells you which run mode this instance is intended for. Author instances are where content is created/edited; publish instances serve read-only content to end users

• p4502 / p4503 — the port number the instance will listen on. By Adobe convention:

  • 4502 = default author instance port

  • 4503 = default publish instance port

  • When running multiple author or publish instances (e.g., for clustering or multiple projects), developers increment the port: 4502, 4512, 4522, etc.

This naming convention isn't enforced by AEM itself — you could name the jar banana.jar and it would still run — but it is critical for you (and your team) to keep track of which instance is which once you have author, publish, and possibly a dispatcher test setup all running locally at once.

Default Ports Reference

The crx-quickstart Folder

The first time you run the jar, AEM extracts itself into a folder called crx-quickstart, created in the same directory as the jar file (unless you specify otherwise). This folder is the entire runtime — your actual AEM installation lives here, not in the jar.

Structure of crx-quickstart

crx-quickstart/
├── app/                    ← Extracted application binaries
├── bin/                    ← Start/stop scripts (start, stop, status)
├── conf/                   ← Server configuration (context.xml, server.xml-like configs)
├── install/                ← Drop-in folder for additional bundles/packages to auto-install on startup
├── launchpad/              ← Felix OSGi launchpad, bundle cache, OSGi config storage
│   └── felix/              ← Bundle cache — all installed OSGi bundles live here
├── logs/                   ← error.log, request.log, access.log, stdout.log — your primary debugging source
├── repository/             ← The actual JCR/Oak content repository (your content, DAM assets, everything)
└── server.log.N            ← Rolled server startup logs

Key folders to know:

• logs/error.log — The single most important file for debugging. Nearly every AEM problem (failed bundle, broken component, startup failure) shows up here first

• repository/ — This is your actual content storage. If you delete this, you lose everything you've authored (pages, DAM assets, workflow history). Back it up before risky operations

• install/ — Drop OSGi bundles (.jar) or content packages (.zip) here and AEM will auto-install them on the next startup — useful for quick one-off deployments

• bin/ — Contains the start/start.bat and stop/stop.bat scripts used to manage the instance as a background service after initial setup

Important operational note: Never manually edit files inside launchpad/felix or repository directly on a running instance — always go through the AEM Web Console, CRXDE Lite, or package manager. Direct filesystem edits to a live repository can corrupt it.

Step-by-Step: Installing AEM Locally via the Jar

Step 1: Verify Java Installation

AEM 6.5 requires JDK 8 or JDK 11 (check your specific AEM version's compatibility matrix — some service packs extend support).

java -version
# Should show something like:
# openjdk version "11.0.x"

If Java isn't installed or is the wrong version, install the correct JDK first and ensure JAVA_HOME is set correctly.

Step 2: Create a Dedicated Folder

Don't run AEM from your Downloads folder or Desktop — create a clean, dedicated directory:

mkdir -p ~/aem/author
cd ~/aem/author

Keep author and publish instances in separate folders — each needs its own crx-quickstart and shouldn't share a working directory.

Step 3: Place the Jar File (and License, if available)

Copy your downloaded quickstart jar into this folder. Rename it following the convention discussed earlier:

cp ~/Downloads/AEM_6.5_Quickstart.jar ~/aem/author/aem-author-p4502.jar

If you have a license.properties file, place it in the same folder as the jar:

cp ~/Downloads/license.properties ~/aem/author/

Step 4: Run the Jar for the First Time (Unpack Only)

On first run, AEM needs to unpack itself. You can do this with a simple command:

cd ~/aem/author
java -jar aem-author-p4502.jar

This will:

1. Extract the crx-quickstart folder

2. Start the OSGi container and Sling

3. Begin the initial bootstrap (installing default bundles, setting up the repository)

4. Launch on the default port (4502) unless specified otherwise

First startup is slow — it can take 3-10 minutes depending on your machine, since it's installing hundreds of bundles and initializing the repository from scratch. Watch crx-quickstart/logs/error.log to monitor progress; the instance is ready when you see a line like:

org.apache.sling.launchpad.base.impl.Sling Starting Felix - framework version 5.x
...
Startup completed

Step 5: Specify Run Mode and Port Explicitly (Recommended)

Rather than relying on defaults, pass explicit JVM and Sling arguments:

java -Xmx4096m -Xms1024m \
  -jar aem-author-p4502.jar \
  -r author -p 4502

Breaking this down:

• -Xmx4096m — Maximum heap size (4GB) — AEM is memory-hungry; don't skimp here

• -Xms1024m — Initial heap size

• -jar aem-author-p4502.jar — The jar to run

• -r author — Run mode (author or publish) — this determines which default configurations and repository structure get applied

• -p 4502 — Port to bind the instance to

For a publish instance, you'd run a separate jar in a separate folder:

java -Xmx4096m -Xms1024m \
  -jar aem-publish-p4503.jar \
  -r publish -p 4503

Step 6: Complete the Setup Wizard

Once startup completes, open a browser to http://localhost:4502 (or 4503 for publish).

• If no license was pre-placed, you'll be prompted to accept the license agreement and enter a license key

• You'll be asked to set the admin password (older versions default to admin/admin, but AEM 6.4+ forces a password change/configuration on first login for security)

• After setup, you'll land on the AEM Start screen

Step 7: Log In and Verify

Default login: admin / admin (unless you changed it during setup).

Navigate to:

• http://localhost:4502/aem/start.html — AEM Start Console

• http://localhost:4502/system/console/bundles — OSGi bundle status (verify everything shows "Active")

If all bundles are active and you can log into the author UI, your installation is successful.

Step 8: Run as a Background Service (Optional but Common)

After the first manual run, you can use the generated scripts in crx-quickstart/bin/ to control the instance without retyping the full Java command:

cd crx-quickstart/bin
./start    # starts AEM in the background
./stop     # gracefully stops AEM
./status   # checks if the instance is running

These scripts read a start.sh/.properties config that remembers the JVM options and run mode you used — but it's worth double-checking the generated start script to confirm memory settings match what you intended.

The -gui Flag: Why It Matters

By default, running java -jar aem-author-p4502.jar from a terminal launches AEM as a foreground console process with no graphical window — it just streams log output to your terminal (and to stdout.log). On most Linux/Mac setups and in headless server environments, this is exactly what you want.

However, on Windows, and in some desktop environments, Adobe's quickstart jar can optionally launch a small graphical status window (showing a basic "AEM is starting..." progress indicator and a shutdown button) using the flag:

java -jar aem-author-p4502.jar -gui

Why -gui Matters

1. Headless environments break without disabling it, or break WITH it: On servers, CI pipelines, Docker containers, or any environment without a display server (no X11/Wayland), launching with GUI-expecting behavior can cause the JVM to throw a HeadlessException or hang trying to initialize a graphics context. In these environments, you explicitly want to avoid -gui (or ensure it's not implicitly triggered) and instead rely on pure console/log output

2. Local desktop convenience: On a local Windows development machine, -gui gives you a visible, clickable window to shut down the instance cleanly without needing to find the terminal or use taskkill — useful for developers less comfortable with the command line

3. Service/background installations should NOT use -gui: When you install AEM as a Windows service or a Linux systemd/init.d service (for a persistent dev or test server), you must run it in non-GUI, non-interactive mode — a GUI flag in a service context has no display to render to and will cause startup failures or hung processes

4. Docker and containerized setups always omit -gui: There's no display server in a container, so this flag is never used there

Rule of thumb: Use -gui only for interactive, local, desktop-based manual runs where you want a visual shutdown control (mostly a Windows convenience). Omit it entirely for Linux/Mac terminal use, scripted automation, CI/CD, Docker, and service installations.

Updating AEM: Applying Service Packs

AEM on-premise doesn't auto-update. Adobe periodically releases Service Packs (SP), Cumulative Fix Packs (CFP), and Feature Packs that you must manually download and install. Staying current matters for security patches and bug fixes.

What a Service Pack Contains

A Service Pack is typically distributed as a .zip file containing one or more content packages (and sometimes OSGi bundles) that patch core AEM functionality, fix security vulnerabilities, or add minor features without requiring a full reinstall.

Steps to Update AEM via Service Pack

Step 1: Back Up Before Updating

Always back up the repository before applying any update:

# Stop the instance first
cd crx-quickstart/bin
./stop

# Back up the entire crx-quickstart/repository folder
cp -r crx-quickstart/repository ~/backups/repository-backup-$(date +%Y%m%d)

Alternatively, use AEM's built-in Offline Backup/Restore tool or the Package Manager's export functionality for a cleaner backup.

Step 2: Download the Correct Service Pack

Log into Adobe's software distribution portal and download the Service Pack matching your exact current AEM version (e.g., AEM 6.5 Service Pack 19 requires you to already be on a compatible prior SP/CFP — check Adobe's release notes for prerequisites).

Step 3: Start the Instance (if not already running)

Service Packs are installed through the running AEM instance itself, not applied to a stopped jar.

cd crx-quickstart/bin
./start

Step 4: Install via Package Manager (Recommended Method)

1. Log in as admin: http://localhost:4502/crx/packmgr/index.jsp

2. Click Upload Package

3. Select the downloaded Service Pack .zip file

4. Once uploaded, click Install next to the package

5. Confirm the installation — AEM will apply the contained bundles/content updates

6. Monitor crx-quickstart/logs/error.log during installation for errors

Step 5: Alternative — Install via install Folder (Auto-Install)

Instead of the UI, you can drop the Service Pack package into the auto-install directory and restart:

cp aem-service-pack-19.zip crx-quickstart/install/
cd crx-quickstart/bin
./stop
./start

On startup, AEM scans the install/ folder and automatically installs any new packages found there.

Step 6: Verify the Update

After installation completes (this can take several minutes and may trigger an automatic instance restart):

• Check Tools → Operations → Web Console → System Information, or navigate to http://localhost:4502/system/console/bundles and look for the updated version strings on core bundles

• Check http://localhost:4502/libs/cq/core/content/welcome.html or the Deployment/Version info in AEM's Web Console to confirm the Service Pack level

• Review error.log for any bundle that failed to start after the update (a common post-update issue when third-party or custom bundles conflict with patched core bundles)

Step 7: Re-test Your Custom Code

Service Packs occasionally change core APIs or behavior. After any update:

• Redeploy and smoke-test your custom bundles/components

• Check deprecated API warnings in logs

• Run your project's regression tests if available

Updating AEM Cloud SDK (For Comparison)

Worth noting: if you're on the AEM Cloud Service SDK instead of classic 6.5, there are no Service Packs at all. Adobe releases a new SDK jar version roughly monthly; you simply download the latest aem-sdk-quickstart.jar and replace your local instance's jar (quickstart conventions for ports and -r author/publish still apply), since Cloud Service itself is continuously updated by Adobe server-side — the SDK just needs to stay reasonably in sync for local development accuracy.

Common Pitfalls During Local Installation

Pitfall 1: Insufficient Memory Allocation

The Mistake: Running java -jar aem-author-p4502.jar with no -Xmx flag, relying on JVM defaults, then watching the instance crash or become unusably slow.

Why It Happens: Default JVM heap sizing is often too small for AEM's bundle-heavy startup.

Fix: Always specify -Xmx4096m (or higher, if your machine allows) explicitly.

Pitfall 2: Port Already in Use

The Mistake: Trying to start a second instance on the default port 4502 while another process (or a previous AEM instance) is still bound to it.

Fix: Check and kill the conflicting process, or simply choose a different port with -p:

# Check what's using port 4502 (Linux/Mac)
lsof -i :4502

Pitfall 3: Running Author and Publish from the Same Folder

The Mistake: Extracting both author and publish instances into the same crx-quickstart parent directory, causing repository conflicts.

Fix: Always use separate folders per instance, as shown in Step 2 above.

Pitfall 4: Forgetting to Stop Before Backing Up

The Mistake: Copying the repository/ folder while AEM is still running, resulting in a corrupted or inconsistent backup due to in-flight writes.

Fix: Always run ./stop and confirm the process has fully exited (check ./status) before copying repository files.

Pitfall 5: Applying Service Packs Out of Order

The Mistake: Installing SP 19 directly on a fresh AEM 6.5 GA instance when SP 19 actually requires an intermediate Cumulative Fix Pack first.

Fix: Always check Adobe's official release notes/compatibility matrix for prerequisite patch levels before installing.

Key Takeaways

Licensing

• AEM requires a valid license key or license.properties file; without one, it runs in a time-limited evaluation mode

• Place license.properties alongside the jar before first launch to skip manual entry

• Never commit license files to version control

The Jar File

• The quickstart jar is a self-extracting bundle containing OSGi (Felix), Sling, and Oak

• Naming conventions like aem-author-p4502.jar aren't enforced by Adobe but are essential team practice for tracking run mode and port across multiple local instances

• Default ports: 4502 for author, 4503 for publish

crx-quickstart Folder

• Created on first run, in the same directory as the jar

• Contains logs/ (your #1 debugging resource), repository/ (your actual content — back this up), install/ (auto-install drop folder), and bin/ (start/stop scripts)

Installation Steps (Summary)

1. Verify Java version compatibility

2. Create a dedicated folder per instance

3. Place the jar (renamed per convention) and license file

4. Run with explicit -Xmx, -r <mode>, and -p <port> flags

5. Complete the browser-based setup wizard

6. Verify via OSGi bundle console

7. Use crx-quickstart/bin/start|stop|status for ongoing management

The -gui Flag

• Shows a graphical shutdown window — a Windows desktop convenience only

• Never use it for headless servers, Docker, CI/CD, or service installations — it can hang or crash the JVM without a display server

Updating via Service Packs

• Always back up the repository (instance stopped) before updating

• Install via Package Manager UI or by dropping the package into crx-quickstart/install/ and restarting

• Verify bundle versions and re-test custom code after every update

• AEM Cloud SDK has no Service Packs — Adobe ships new SDK jar versions directly instead

On-Prem vs. Cloud

• AEM 6.5 (jar): self-managed, license-key based, manual Service Pack updates

• AEM as a Cloud Service: Adobe-managed SaaS, local dev via Cloud SDK jar, continuous updates, Cloud Manager-driven CI/CD, entitlement-based licensing