AEM Cloud Service vs. On-Premise
1. The Core Architectural Difference
Before comparing features and costs, you need to understand what you’re actually choosing
between. These are not the same product with different hosting. They are fundamentally different
architectural models.
| Stack Layers | Key Frameworks | Min Read Time | Skill Level |
|---|---|---|---|
| 6 core layers | OSGi, JCR, Sling, HTL | ~20 minutes | Intermediate–Expert |
1. The AEM Technology Stack
AEM doesn’t run on magic. It runs on a carefully layered set of open standards. Understanding
those layers is the difference between being reactive (“something is broken”) and proactive (“I know
exactly what to check”).
The full stack, from bottom to top:
| Layer | Technology | What It Does |
|---|---|---|
| 6 (Top) | AEM Applications | Sites, Assets, Forms — the products you work with |
| 5 | Adobe Granite | AEM's custom layer: workflows, tagging, replication, security |
| 4 | Apache Sling | Maps URLs to content; drives the request pipeline |
| 3 | JCR / Apache Oak | Content repository — everything is a node |
| 2 | OSGi (Apache Felix) | Modular runtime — bundles, services, dynamic wiring |
| 1 (Base) | JVM (Java) | The foundation — all of the above runs on the JVM |
2. OSGi — The Modular Heart
OSGi is beautiful, until it isn’t. When it works, you get a hot-reloadable, loosely-coupled runtime
where services wire themselves together at startup. When it breaks, you get a cascade of bundle
failures that look completely unrelated to your change.
What Is OSGi?
OSGi (Open Services Gateway initiative) is a Java-based component system. In AEM, it’s
implemented by Apache Felix. The entire AEM application — including your custom code — runs
as a set of OSGi bundles inside this container.
The Four Building Blocks
Bundles
A bundle is a standard JAR file with extra metadata in its MANIFEST.MF. That metadata tells OSGi
what packages the bundle exports (makes available) and what packages it imports (depends on).
Services
A service is a Java interface implemented by one or more bundles and registered in a service
registry. Other bundles discover services through the registry — they never depend on a specific
implementation class.
Components
A component is a Java class annotated with @Component (from the OSGi DS annotations). When
the bundle activates, OSGi DS scans these annotations and instantiates/wires components
automatically.
Configurations
Every component can have a corresponding factory configuration. Configurations are stored in the
JCR repository (under /apps/config) or as .cfg.json/.config files in your project. They are
environment-aware through run modes.
Production Gotcha — The Silent Run-Mode Miss
Your OSGi configuration for prod is under /apps/config.prod but your run modes are set to
author,publish — not prod. Everything deploys without an error. Your production config is silently
ignored. Always validate run-mode-specific configs with the Felix console after deployment.
OSGi Bundle Lifecycle
- Installed — Bundle JAR is in the OSGi container
- Resolved — All package imports are satisfied
- Starting — Bundle's Activator.start() is called
- Active — Bundle is running, services are registered
- Stopping — Bundle's Activator.stop() is called
- Uninstalled — Bundle is removed from the container
Production Gotcha — The OSGi Cascade Failure
You update Bundle A, which exports a package that Bundle B imports. Bundle B suddenly goes from
Active to Installed state (its import is no longer satisfied during the update window). Bundle C
depends on a service from Bundle B — it also goes down. One bundle update causes three services
to disappear simultaneously. The Felix console’s Bundles view is your first diagnostic tool.
3. JCR & Apache Oak — Everything Is a Node
The Java Content Repository (JCR) is the storage backbone of AEM. Unlike a relational database
with rows and columns, JCR stores everything — content, configuration, templates, component
code, user data — as a hierarchy of nodes and properties.
The Repository Structure
The JCR tree has several standard root paths you’ll work with every day:
| Path | Purpose | Example |
|---|---|---|
| /content | All authored content — pages, assets, experience fragments | /content/we-retail/en/home |
| /apps | Custom application code — components, templates, OSGi configs | /apps/my-project/components/page |
| /libs | AEM product code — do not modify directly | /libs/granite/ui/components/coral/foundation |
| /conf | Editable template definitions and context-aware configs | /conf/my-project/settings/wcm/templates |
| /var | Variable data — workflow instances, audit logs, replication queues | /var/workflow/instances |
| /home | Users, groups, and their profile data | /home/users/admin |
Node Types
Every node has a primary type that defines what properties and child nodes it can have. Common
node types in AEM include:
- nt:unstructured — Unconstrained node; accepts any property
- nt:file / nt:resource — Binary file storage
- cq:Page — A content page (has a jcr:content child)
- cq:PageContent — The content node of a page
- dam:Asset — A Digital Asset Manager asset
- cq:Component — An AEM component definition
Apache Oak — The JCR Implementation
Apache Oak is the JCR 2.0 implementation powering AEM 6.x and AEM as a Cloud Service. Oak
supports two storage backends:
- TarMK (Tar Micro Kernel) — File-based; default for author instances. Good for single-node setups.
- MongoMK (Mongo Micro Kernel) — MongoDB-backed; used for clustered author environments to support multiple active author nodes.
Sling Resource Resolution and the JCR
Sling maps incoming URLs to JCR nodes. When a request arrives for /content/my-site/home.html,
Sling walks the JCR tree to find a node at /content/my-site/home, then looks for the component
referenced by that node’s sling:resourceType property to render it.
4. Apache Sling — The Request Pipeline
Apache Sling is the web framework that bridges the JCR and your component code. Its core insight
is deceptively simple: every URL maps to a resource in the JCR, and every resource has a type
that determines how it’s rendered.
URL Anatomy in Sling
A Sling URL follows a specific pattern that experienced AEM developers read like code:
| Path | Selectors | Extension | Suffix |
|---|---|---|---|
| /content/we-retail/home | model.json | .html | /some/extra/path |
The selectors (.model.json in the example above) are what drive multi-format rendering. The same
resource at /content/page can render as HTML with no selector, as JSON with .model, and as an
image thumbnail with .thumb.80.80 — all served by different scripts without any routing
configuration.
Security Gotcha — Selector Injection
Sling’s open selector model is powerful but dangerous. An attacker requesting
/content/page.infinity.json can dump an entire JCR subtree as JSON. Always configure your Sling
URL mappings and Dispatcher rules to whitelist only the selectors your application exposes. The
/system/console/slinglog viewer will show you every selector hit in real time.
The Sling Request Pipeline
When a request arrives, Sling processes it through a fixed pipeline:
- URL Decomposition — Parse path, selectors, extension, suffix
- Resource Resolution — Find the JCR node matching the path
- Servlet/Script Resolution — Find the best script to render the resource based on resourceType, selectors, and extension
- Request Filters — Pre-processing filters run (authentication, access control)
- Script Execution — HTL/JSP/Servlet renders the response
- Response Filters — Post-processing filters run (header manipulation, etc.)
Sling Models
Sling Models are Plain Old Java Objects (POJOs) annotated to automatically inject resource
properties and OSGi services. They’re the recommended way to write business logic in AEM.
5. HTL (HTML Template Language)
HTL replaced JSP as the recommended server-side templating language for AEM. If you’re still
writing Java directly in your template files, you’re doing it wrong — and you’re creating a security
risk.
Why HTL Over JSP?
- XSS protection is built-in — HTL escapes output context-appropriately by default
- Separation of concerns — Logic lives in Sling Models; HTL is pure presentation
- No scriptlets — Java code cannot be embedded inline in HTL files
- Security by design — Server-side-only execution; client never sees HTL source
HTL Syntax Essentials
data-sly-use — Load a Sling Model
data-sly-list — Iterate a Collection
data-sly-test — Conditional Rendering
data-sly-include / data-sly-resource — Composition
Conclusion
AEM is not a black box. It’s six well-documented open-source technologies stacked on top of each
other, each with a specific responsibility, a standard API, and a console for introspection.
The developers who excel in AEM are not the ones who memorize the most APIs. They’re the ones
who understand the shape of the system — who know that a missing OSGi configuration in a run-
mode folder is why prod behaves differently than dev, that a Dispatcher filter rule is why a perfectly
valid URL returns 403, and that a Sling resourceType miss is why a component renders nothing.
You now have that map. The next step is to open the Felix console on a real AEM instance and
start exploring. The architecture is all there, visible and interactive, waiting for you to poke at it.
