If you have built on AEM 6.5 or earlier, AEM as a Cloud Service (AEMaaCS) will feel familiar at the code level and different at the operations level. The Java APIs, Sling, OSGi and JCR are still there. What changed is how code reaches production, who controls the platform upgrades, and what you are allowed to change at runtime.

This post explains the platform model, the vocabulary you will hear on every project (program, environment, pipeline, RDE, Dispatcher, CDN), and the rules around mutable and immutable content. It ends with a hands-on walk through a program in Cloud Manager so you can see those concepts in the real UI.

Table of contents

• Why this matters
• Who should read this
• Prerequisites
• The platform model: service, not server
• Continuous updates
• Mutable vs immutable content
• Core vocabulary
• AEM 6.5 vs AEMaaCS for developers
• Hands-on: explore a program in Cloud Manager
• Common mistakes and troubleshooting
• Hands-on challenge
• Key takeaways
• Knowledge check
• Frequently asked questions
• Continue your learning

---

Why this matters

Most AEM failures on cloud projects are not Java bugs. They come from a developer assuming they can change something at runtime that the platform treats as read-only, or from a deployment that skipped a step because the team was used to copying a package into CRXDE Lite. AEMaaCS removes those shortcuts on purpose. Once you understand why, the rules stop feeling arbitrary.

Understanding the model early also makes later lessons easier. OSGi configuration, repoinit, Dispatcher rules and pipelines all follow from the same ideas: code and infrastructure are versioned and deployed; content is data that is changed at runtime.

Who should read this

This post is for developers and technical leads who are new to AEMaaCS, or who have worked on AEM 6.x and want a precise picture of what is different. It is also useful for QA engineers who need to know which environment a defect belongs to. You do not need cloud or DevOps experience, but you should be comfortable with Java, Maven and the basic AEM author UI.

Prerequisites

• Basic AEM knowledge: pages, components, the author and publish instances, and the JCR repository.
• Access to an AEMaaCS program in Adobe Cloud Manager. If you do not have one, read along and use the screenshots.
• Lesson 05 in this series, AEM Project Archetype and Repository Structure for AEMaaCS, for the project layout used in later examples. The full course roadmap is at /aem-cloud/.

The platform model: service, not server

In AEM 6.5 you installed AEM on infrastructure you controlled, chose the Java version, scheduled the upgrades and tuned the JVM. In AEMaaCS, Adobe runs the author, publish, Dispatcher and CDN layers for you. You do not get SSH access to the hosts, and you do not install service packs yourself.

What you do own is your code, your OSGi configuration, your content packages (within the rules below) and your Dispatcher rules. Cloud Manager is the single delivery path for code into dev, stage and production. That is the contract: the platform is managed, and your delivery is automated and repeatable.

Note:- Adobe documents Cloud Manager as the only way to deploy code to dev, stage and production environments. Use RDEs for fast iteration and debugging, not as a release path.

Continuous updates

AEMaaCS gets platform updates on a fixed cadence instead of waiting for a major version. Adobe separates two things you need to keep apart in your head:

• Version updates: Adobe applies monthly and daily maintenance releases to the platform. You do not schedule these, and your code does not need to change for most of them.
• Your releases: the code, configuration and content you ship. You control when these go out, through a Cloud Manager pipeline.

The practical consequence is that your code must not depend on a specific platform patch. Keep your local SDK in step with the monthly release, because the SDK APIs and the quickstart jar follow the platform. If your local build passes against an old SDK but fails in the cloud, the SDK version is the first thing to check.

Mutable vs immutable content

This is the rule that surprises most developers. The repository is split into two kinds of paths:

• Immutable: /apps and /libs. Code, component definitions, client libraries and OSGi configuration arrive only through a deployment. You cannot change these at runtime.
• Mutable: /content, /conf, /var, /etc, /oak:index, /system and /tmp. Authors and runtime processes write here, and content packages can install here.

Two rules follow from this split. First, a single content package cannot mix immutable and mutable paths. If it tries, the build fails with a “MIXED type” message, so split your packages by type. Second, mutable content installs follow a fixed order: indexes first, then service users, ACLs and node types during startup, then everything else after the switchover. Mutable content has no rollback, so test content packages on a lower environment before they reach production.

A common pattern is to put everything the platform needs at startup, such as service users, into repoinit rather than a content package. Repoinit runs as part of the immutable deployment, which keeps it reproducible.

Core vocabulary

These terms are used across Cloud Manager, the documentation and your team chat. Get them right early.

Term	What it means	Where you see it
Program	The top-level container for your AEMaaCS project. It holds environments, pipelines and users. Programs are production or sandbox.	Cloud Manager home page, program ID such as 12345
Environment	A set of author, publish and Dispatcher instances. Typical types are dev, stage, prod and RDE.	Cloud Manager, Environments tab; environment ID such as 67890
Pipeline	An automated run that builds, tests and deploys code or configuration to an environment. Types include full-stack, front-end, web-tier and config pipelines.	Cloud Manager, Pipelines tab
RDE	Rapid Development Environment. A cloud environment for fast sync and debug, with a Cloud Service author. You get one per program.	Add Environment, then Rapid Development
Dispatcher	The Apache-based caching and filtering layer in front of publish. It enforces the rules you define in the Dispatcher configuration.	Dispatcher SDK, the dispatcher/src folder
CDN	The content delivery network at the edge. It caches responses and forwards requests to the Dispatcher.	Cloud Manager CDN settings, config pipeline files

Every environment belongs to one program. A sandbox program comes with a dev environment and a non-production pipeline already created, which makes it a good place to practise. A typical Sites-only production program has one prod, one stage, one dev environment and one RDE.

AEM 6.5 vs AEMaaCS for developers

Topic	AEM 6.5 (on-premises or managed)	AEMaaCS
Hosting and upgrades	You plan and run upgrades and service packs	Adobe runs the platform and applies monthly and daily releases
Deploying code	Package Manager or your own CI scripts	Cloud Manager pipelines only, for dev, stage and prod
Runtime config	OSGi config through Web Console or CRXDE Lite	OSGi config as .cfg.json files in the repo, deployed through pipelines
Editing /apps in CRXDE Lite	Possible on author, not recommended	Not possible. Changes are made in code and redeployed
Service users	Created in the UI or with scripts	Created with repoinit in the deployed code
Dispatcher	Configured on your servers	Managed by Adobe, with rules you deploy from your repo
Local development	Local author on your machine	AEM SDK quickstart jar locally, plus an RDE in the cloud

Hands-on: explore a program in Cloud Manager

In this section you will look at a program and its environments without changing anything. Use a sandbox or a non-production program if you have one. Do not run deployments as part of this exercise.

Step 1: Open your program

Sign in to Adobe Cloud Manager at my.cloudmanager.adobe.com. Select your organization, then open the program. Note the program ID shown in the program details. The examples in this series use program 12345.

Step 2: Review the environments

Open the Environments view. For each environment, note its type (Development, Stage, Production or Rapid Development), its status, and the environment ID. The examples in this series use environment 67890. An RDE shows up here too; it is the one you will set up in Lesson 04.

Step 3: Review the pipelines

Open the Pipelines view and find the full-stack pipeline for production and for non-production. Open the last execution of one of them and read its phases. You will see that code is built, tested and deployed as one unit, and that configuration can be deployed by a separate config pipeline.

Step 4: Check the platform version on an environment

Open an environment and locate the environment details. Record the AEM version it reports. You will compare this with the SDK version later, because the Maven dependency for the SDK API must match it.

Step 5: Inspect mutable and immutable paths in a running author

Open the Developer Console from your dev environment, then open CRXDE Lite. Browse to /apps and /content and compare them. Try to save a change under /apps. You should see that the change is not allowed on a cloud environment. Do not try to work around it; the correct fix is always in code.

Note:- Read-only inspection is enough for this lesson. Do not edit production content from CRXDE Lite.

Common mistakes and troubleshooting

Symptom	Likely cause	What to do
Build fails with a “MIXED type” message	One content package contains both immutable (/apps) and mutable paths	Split the package into an apps package and a content package
A change made in CRXDE Lite under /apps disappears after deployment	Immutable paths are reset to the deployed version	Move the change into the codebase and deploy it through a pipeline
Local build works, cloud build fails on an API	SDK version does not match the platform version	Update the local SDK after the monthly release and rebuild
Team deploys to production by copying a package	Bypasses Cloud Manager and its quality gates	Deploy through the production pipeline only
Content from stage is missing on dev	Mutable content is not copied between environments	Use a content package or the documented content-copy process for that environment

Hands-on challenge

Pick one program you have access to and answer these questions in your own notes, using only Cloud Manager and the Developer Console: How many environments does it have, and which types? Which pipelines exist for production? Which AEM version is the dev environment running? Which of /apps, /content and /conf is immutable? If you cannot answer one, record it as a gap to close before Lesson 04.

Key takeaways

✅ AEMaaCS is a managed service. Adobe runs the platform, and you deliver code and configuration.
✅ Cloud Manager pipelines are the only route to dev, stage and production.
✅ Version updates from Adobe are separate from your releases.
✅ /apps and /libs are immutable. Content paths are mutable and have no rollback.
✅ Keep program, environment, pipeline, RDE, Dispatcher and CDN straight. Every later lesson uses them.

Knowledge check

1. Which path is the only supported way to deploy code to dev, stage and production?

Cloud Manager pipelines. RDEs are for sync and debug, and deploying by package is not a release path.

2. Why does a content package that mixes /apps and /content fail?

Immutable and mutable paths must be installed through different mechanisms, so one package cannot contain both. The build reports a “MIXED type” error.

3. What is the difference between a version update and a release?

A version update is a platform change that Adobe applies on a fixed cadence. A release is your code, configuration or content, which you deploy through a pipeline.

4. Where should a service user be created on AEMaaCS?

In repoinit, as part of the deployed code, so the setup is reproducible across environments.

5. What does a sandbox program give you?

A dev environment and a non-production pipeline are created automatically, so you can practise without setting up a production program.

Frequently asked questions

Can I install a package directly on the production author?

No. Production changes go through the production pipeline. Use RDEs or dev environments to test first.

Do I need to learn the Cloud Manager UI as a developer?

Yes, at least the pipeline and environment views. Most failed releases are diagnosed there first.

Does AEMaaCS still use OSGi?

Yes. Bundles, services and configurations are still OSGi. What changes is how they are deployed.

Is the AEM SDK the same as AEMaaCS?

No. The SDK is the local quickstart and API set you build against. The cloud service is the managed platform.

Where do I start if I am new to AEMaaCS?

Read this post, then set up your local environment in Lesson 04 and work through the archetype lesson.

Continue your learning

• Previous lesson: none. This is the first lesson in Module 1; start with the course roadmap at /aem-cloud/.
• Next lesson: Lesson 02, AEMaaCS Environments: RDE vs Dev, Stage and Production (unpublished draft; see the roadmap for updates).
• Practice quiz: AEM Cloud Service practice test 1.
• Roadmap: AEM as a Cloud Service learning roadmap.
• Background on the older platform: AEM as a Cloud Service overview.