Skip to main content

AEM as a Cloud Service

AEM as a Cloud Service (AEMaaCS) is Adobe's cloud-native, fully managed version of Adobe Experience Manager. It replaces the traditional on-premise and Adobe Managed Services (AMS) hosting models with a platform that auto-scales, auto-updates, and enforces strict separation between code and content. Understanding its constraints and capabilities is essential -- many patterns that work on AEM 6.5 do not apply on AEMaaCS.

Key Differences from AEM 6.5 / On-Premise​

AspectAEM 6.5 / On-PremAEMaaCS
DeploymentPackage Manager, WebDAV, manual installCloud Manager pipelines only
InfrastructureSelf-managed serversFully managed, auto-scaled by Adobe
UpdatesManual upgrades (months/years)Continuous updates (monthly, automatic)
/apps and /libsMutable at runtimeImmutable -- deployed via pipeline only
/etc/designsDesign mode for component configDeprecated -- use editable templates and policies
Custom run modesAny custom run mode nameOnly author, publish, preview + dev, stage, prod
CRXDE LiteAvailable in all environmentsAvailable on dev/RDE only, not in stage/prod
Repository accessDirect JCR access, WebDAVDeveloper Console for logs; no direct JCR in prod
Content replicationReplication agents (manual config)Content Distribution (Sling, automatic)
Pricing modelPerpetual licenseSubscription (per program)
ScalingManual (add servers)Automatic (horizontal auto-scaling)

Programs and Environments​

Cloud Manager programs​

A program is the top-level organisational unit in Cloud Manager. Each program contains a set of environments, pipelines, and configuration.

Program typePurpose
ProductionFull set of environments (dev, stage, prod) for a live site
SandboxTrial and experimentation; auto-hibernates after inactivity; limited features

Environment types​

EnvironmentPurposeKey characteristics
DevelopmentDay-to-day development and testingMutable; CRXDE available; can install packages manually
Rapid Dev (RDE)Fast iteration without full pipelineDeploy in seconds via CLI; no build step; limited lifespan
StagePre-production validationMirrors prod topology; immutable; pipeline-only deployment
ProductionLive siteImmutable; auto-scaled; no CRXDE; no Package Manager
PreviewContent preview before publishOptional; separate tier for preview workflows

Immutable vs Mutable Areas​

The most fundamental constraint of AEMaaCS is the distinction between immutable (code, deployed via pipeline) and mutable (content, managed at runtime) areas of the repository.

Immutable (deployed via pipeline)​

These paths are overwritten on every deployment and cannot be changed at runtime:

PathContains
/apps/Component definitions, Sling Models, services, HTL scripts
/libs/AEM product code (never modify)
/oak:index/Custom Oak index definitions
/apps/*/config/OSGi configurations
/apps/*/i18n/i18n dictionaries

Mutable (content, managed at runtime)​

These paths persist across deployments and are managed by authors or at runtime:

PathContains
/content/Pages, experience fragments
/content/dam/Digital assets
/content/cq:tags/Tags and taxonomies
/conf/Editable templates, policies, cloud service configs, CA Config
/var/Workflows, audit logs, eventing
/home/Users and groups
/tmp/Temporary data

Repoinit for bootstrap content​

Since you cannot manually create nodes in /apps at runtime, use Repository Initialisation (repoinit) scripts to bootstrap required structures:

ui.config/.../org.apache.sling.jcr.repoinit.RepositoryInitializer~myproject.cfg.json
{
    "scripts": [
        "create path /content/mysite(sling:OrderedFolder)",
        "create path /content/dam/mysite(sling:OrderedFolder)",
        "",
        "create service user myproject-service with path system/myproject",
        "set ACL for myproject-service",
        "    allow jcr:read on /content/mysite",
        "    allow rep:write on /content/mysite",
        "end"
    ]
}

Content Distribution (replacing replication)​

AEMaaCS replaces the traditional replication agent model with Sling Content Distribution. Content published on the author tier is distributed to publish instances automatically -- there are no manually configured replication agents.

Key differences:

  • No replication agents to configure or troubleshoot
  • Content is distributed to all publish instances simultaneously
  • Distribution is asynchronous -- there is a short delay (seconds to minutes)
  • The distribution queue is visible in the Distribution Agent UI on author
  • Tree activation distributes an entire subtree at once
  • Failed distributions are retried automatically

Invalidating the CDN/Dispatcher cache​

On publish, AEMaaCS automatically invalidates the Dispatcher cache and purges the CDN for the affected paths. You do not need to configure flush agents.

For Edge Delivery Services or custom CDN setups, configure push invalidation in the CDN config.

Rapid Development Environments (RDEs)​

RDEs are lightweight environments designed for rapid iteration. Instead of running a full Cloud Manager pipeline (which takes 30-60 minutes), you deploy directly from your local machine in seconds using the Adobe I/O CLI.

Setup​

# Install the RDE plugin
aio plugins:install @adobe/aio-cli-plugin-aem-rde

# Login
aio login

# Select your org, program, and environment
aio aem:rde:setup

Deploying to an RDE​

# Deploy a content package
aio aem:rde:install target/myproject.ui.apps-1.0-SNAPSHOT.zip

# Deploy an OSGi bundle
aio aem:rde:install target/myproject.core-1.0-SNAPSHOT.jar

# Deploy Dispatcher configuration
aio aem:rde:install dispatcher/src --type dispatcher

# Deploy an OSGi config file
aio aem:rde:install ui.config/src/.../com.myproject.MyConfig.cfg.json --type osgi-config

# Check deployment status
aio aem:rde:status

# Reset the environment (clean slate)
aio aem:rde:reset

When to use RDEs vs dev environments​

ScenarioRDEDev environment
Quick feature iterationBestSlow (pipeline)
Testing OSGi config changesBestOK
Full integration testingNoYes
Load testingNoYes
Dispatcher testingPartialFull
Collaboration (shared state)LimitedYes

Developer Console​

The Developer Console replaces CRXDE Lite and the Felix Web Console for non-development environments. It provides read-only access to diagnostics and runtime information.

Access it at: https://dev-console-<env-id>.adobeaemcloud.com/

Available features​

FeatureDescription
StatusEnvironment health, instance status, version info
BundlesList OSGi bundles, check state (Active, Resolved, Installed)
ComponentsList OSGi (Declarative Services) components and their state
ConfigurationsView OSGi configurations (read-only)
Sling ModelsList registered Sling Models and their adapters
Oak IndexesView index definitions and reindexing status
Repository browserBrowse the JCR tree (read-only)
LogsDownload or tail log files (error.log, request.log, etc.)
Query performanceView slow queries and index usage
tip

For production debugging, the Developer Console log viewer is your primary tool. You can filter by log level, logger name, and time range. Download full log files for offline analysis.

Cloud SDK for Local Development​

The AEM as a Cloud Service SDK lets you run a local AEM instance that matches the cloud runtime. Always develop against the SDK to catch compatibility issues early.

Downloading the SDK​

  1. Go to Software Distribution
  2. Download the latest aem-sdk-quickstart-*.jar and Dispatcher tools
  3. The SDK is updated monthly in sync with AEMaaCS releases

Running locally​

# Start the author instance
java -jar aem-sdk-quickstart-*.jar -p 4502

# Start a publish instance
java -jar aem-sdk-quickstart-*.jar -p 4503 -r publish

# Run the Dispatcher SDK
cd dispatcher-tools
./bin/docker_run.sh ../dispatcher/src host.docker.internal:4503 8080

SDK vs production differences​

AspectSDKAEMaaCS production
ScalingSingle instanceAuto-scaled cluster
CDNNone (localhost)Fastly CDN
Content DistributionLocal replicationSling Content Distribution
Startup time2-5 minutesManaged by Adobe
UpdatesManual downloadAutomatic
Oak persistenceSegment tarComposite node store

Content Migration​

Content Transfer Tool (CTT)​

The Content Transfer Tool migrates content from AEM 6.x to AEMaaCS:

  1. Extraction -- CTT reads content from the source AEM instance
  2. Upload -- Content is uploaded to a cloud staging area (blob store)
  3. Ingestion -- Content is imported into the target AEMaaCS environment

CTT supports incremental transfers (delta), so you can do a bulk initial migration followed by smaller top-ups closer to go-live.

Cloud Acceleration Manager (CAM)​

CAM is a companion tool that helps plan and execute the migration:

  • Best Practice Analyzer (BPA) -- scans your AEM 6.x instance and flags compatibility issues (deprecated APIs, unsupported configs)
  • Repository Modernizer -- restructures content packages to separate /apps (code) from /content (mutable content)
  • Index Converter -- converts AEM 6.x index definitions to the AEMaaCS format
  • Dispatcher Converter -- converts AMS/on-prem Dispatcher configs to the AEMaaCS structure

Common migration challenges​

ChallengeSolution
Custom run modesMap to standard run modes (dev, stage, prod)
/etc/designsMigrate to editable templates and policies
Custom login modulesUse AEM IMS (Adobe Identity Management)
Workflow launchers with /libs pathsUpdate to /content or /var paths
Large binary assetsUse CTT with streaming; plan for transfer time
Custom Oak indexesConvert with Index Converter; deploy via /oak:index/ in code
Custom replication agentsReplace with Content Distribution (automatic)

Deprecated and Removed Features​

These features available on AEM 6.5 are not available or deprecated on AEMaaCS:

FeatureStatusReplacement
CRXDE Lite (prod)RemovedDeveloper Console (read-only)
Package Manager (prod)RemovedCloud Manager pipelines
Classic UIDeprecatedTouch UI
Design mode / /etc/designsDeprecatedEditable templates and policies
Static templatesDeprecatedEditable templates
Custom run modesRemoveddev, stage, prod only
JSP scriptingDeprecatedHTL (Sightly)
Replication agentsReplacedSling Content Distribution
Workflow purge schedulersChangedAdobe-managed maintenance windows
loginAdministrative()RemovedService users with getServiceResourceResolver()
WebDAV accessRemovedAssets HTTP API, AEM Desktop App
VLT (FileVault)LimitedAEM Repo Tool, RDE CLI

OSGi Configuration on AEMaaCS​

OSGi configurations on AEMaaCS follow a strict folder-based run mode structure:

ui.config/src/main/content/jcr_root/apps/myproject/osgiconfig/
├── config/                    ← All environments, all tiers
│   └── com.myproject.MyService.cfg.json
├── config.author/             ← Author tier only
│   └── com.myproject.AuthorOnlyService.cfg.json
├── config.publish/            ← Publish tier only
│   └── com.myproject.PublishOnlyService.cfg.json
├── config.dev/                ← Dev environment only
│   └── com.myproject.MyService~dev.cfg.json
├── config.stage/              ← Stage environment only
│   └── com.myproject.MyService~stage.cfg.json
├── config.prod/               ← Production only
│   └── com.myproject.MyService~prod.cfg.json
├── config.author.dev/         ← Author tier, dev environment
│   └── ...
└── config.publish.prod/       ← Publish tier, production
    └── ...

Secret configurations​

Sensitive values (API keys, passwords) must not be stored in code. Use Cloud Manager environment variables or secret configs:

com.myproject.IntegrationService.cfg.json
{
    "apiKey": "$[secret:MY_API_KEY]",
    "endpoint": "$[env:INTEGRATION_ENDPOINT]"
}
  • $[secret:NAME] -- resolves from Cloud Manager secret variables (encrypted)
  • $[env:NAME] -- resolves from Cloud Manager environment variables

Set them in Cloud Manager: Environments > Environment Variables.

Auto-Scaling and Performance​

AEMaaCS automatically scales both the author and publish tiers based on load:

  • Publish tier -- scales horizontally (more instances) based on request volume
  • Author tier -- scales vertically and horizontally for concurrent authoring
  • CDN -- Fastly CDN with global PoPs handles edge caching automatically
  • Maintenance windows -- Adobe runs compaction, garbage collection, and index optimization during scheduled maintenance windows

What you control​

AspectYour responsibility
Cache-Control headersSet appropriate TTLs for static and dynamic content
CDN configurationcdn.yaml for redirects, transformations, origin selectors
Dispatcher rulesCache rules, filters, rewrite rules
Oak indexesDefine custom indexes for query performance
Asset processingConfigure processing profiles for image renditions

What Adobe manages​

AspectAdobe's responsibility
InfrastructureServers, networking, storage, scaling
UpdatesMonthly AEM updates, security patches
MonitoringUptime monitoring, alerting
BackupsAutomated backups, point-in-time recovery
SSL/TLSCertificate management for *.adobeaemcloud.com
MaintenanceCompaction, garbage collection, index optimization

Networking​

AEMaaCS environments run in isolated VPCs. By default, they can only make outbound requests to public internet endpoints. For connecting to private services, Adobe offers Advanced Networking:

Networking typeUse case
Flexible port egressConnect to external services on non-standard ports (e.g., SMTP on 587)
Dedicated egress IPWhitelist a fixed IP for outbound connections to firewalled services
VPNSite-to-site VPN for connecting to private corporate networks

Configure via Cloud Manager API or CLI:

# Enable flexible port egress
aio cloudmanager:set-environment-advanced-networking \
  --type flexiblePortEgress \
  --program-id 12345 \
  --environment-id 67890

For SMTP (email sending), flexible port egress with port forwarding is required. See the E-Mail Service page for a detailed setup guide.

Best Practices​

Develop against the Cloud SDK from day one​

Don't develop against AEM 6.5 and "migrate later." Use the Cloud SDK as your local development runtime to catch incompatibilities immediately.

Treat code and content as separate concerns​

Code (/apps, OSGi configs, indexes) is deployed via pipelines. Content (/content, /conf, /var) is managed at runtime. Never mix them in the same package.

Use service users, not admin sessions​

loginAdministrative() does not exist on AEMaaCS. All background operations must use service users with explicitly granted permissions.

Embrace repoinit for environment setup​

Use repoinit scripts for creating service users, groups, ACLs, and required paths. They run on every deployment and are idempotent.

Keep Dispatcher configs simple and validated​

Run ./bin/validator full locally before every commit. Cloud Manager will reject invalid Dispatcher configurations and block the entire deployment.

Use RDEs for rapid iteration​

Don't wait for 45-minute pipeline runs during development. Use RDEs to test changes in seconds, then promote to dev via the pipeline.

Plan your migration early​

Run the Best Practice Analyzer (BPA) early in the project. Many compatibility issues (custom run modes, deprecated APIs, /etc/designs) require architectural changes that take time.

Common Pitfalls​

PitfallSolution
Code changes not reflected after deployCheck that the pipeline completed; verify the bundle is active in Developer Console
LoginException for service usersEnsure repoinit scripts run before service user mappings; check ACLs
Content missing after deploymentContent packages must go into ui.content, not ui.apps; mutable content is not overwritten
Custom run mode configs ignoredAEMaaCS only supports standard run modes (dev, stage, prod, author, publish)
Slow queries in productionDefine custom Oak indexes in /oak:index/; use the Developer Console query performance tool
SMTP not workingConfigure Advanced Networking (flexible port egress) for port 587; see E-Mail Service
Assets not renderingCheck asset processing profiles; verify Dynamic Media configuration
Dispatcher cache not invalidatingCache invalidation is automatic on AEMaaCS; check CDN cache if stale content persists
ClassNotFoundException after updateAdobe's monthly updates may remove deprecated APIs; check release notes and fix code
CRXDE not availableExpected in stage/prod; use Developer Console repository browser (read-only)

See also​