Most AEMaaCS performance and caching problems are routing problems in disguise. A page is slow, stale or missing, and the cause is not in your component. It is in the layer that answered the request: the CDN, the Dispatcher, or publish. You cannot debug those layers well until you can name what each one does.

This post traces one request end to end: from the browser, through the CDN and Dispatcher, to publish. It then follows the two other flows that matter, content (authoring to publish) and code (Cloud Manager to each environment), and shows you how to read cache headers and logs to find out which layer served a response.

Table of contents

• Why this matters
• Who should read this
• Prerequisites
• The request path: browser, CDN, Dispatcher, publish
• Author and publish: where content and code live
• How content flows from author to publish
• How code flows through Cloud Manager
• Caching at the Dispatcher and the CDN
• Hands-on: trace a request with curl
• Hands-on: read the Dispatcher configuration
• Where each concern lives
• Troubleshooting table
• Hands-on challenge
• Key takeaways
• Knowledge check
• Frequently asked questions
• Continue your learning

Why this matters

In AEM 6.5 most teams ran their own Dispatcher and CDN, so the path was obvious. On AEMaaCS, Adobe operates the publish, author and Dispatcher tiers, and the CDN sits in front of them. That means the path has more hops, some of which you configure and some of which you do not. Knowing which hop owns which behaviour is the fastest way to resolve an incident.

Who should read this

This post is for developers, architects and DevOps engineers who work on an AEMaaCS program and need to explain or debug the request path. If you have only built components, read it before you touch caching rules or the Dispatcher configuration.

Prerequisites

• Lesson 01 in this series, the AEMaaCS platform model, for the terms program, environment and pipeline.
• Basic HTTP knowledge: request methods, status codes and the Cache-Control and Age headers.
• A terminal with curl. The full course roadmap is at /aem-cloud/.

The request path: browser, CDN, Dispatcher, publish

For a public page, the request travels through four hops:

1. Browser sends a request to your site hostname, for example www.mysite.example.
2. CDN at the edge checks its own cache. On a hit it returns the cached response and stops here. On a miss it forwards the request to the Dispatcher.
3. Dispatcher applies its filters and rewrite rules. It can serve a response from its own file cache, reject the request, or forward it to publish.
4. Publish resolves the resource, runs Sling and your components, and returns the HTML, JSON or asset.

Each hop can change the response. The Dispatcher can rewrite a path, the CDN can add or remove headers, and a stale response at any layer can hide a fix you just deployed. When you debug, check the hops in order from the outside in.

Author and publish: where content and code live

Authors edit content on the author tier. Publish serves it to visitors. In AEMaaCS, author and publish are separate services with their own repository, and they do not share a live copy. Code is deployed to both through the same Cloud Manager pipeline, so an environment runs the same bundles and components on both tiers.

The most common mistake is to assume that publishing a page makes its code change visible. It does not. Publishing copies content. A code change needs a deployment, and a deployment clears and warms the Dispatcher cache.

How content flows from author to publish

When an author activates a page, the replication step copies the content node to publish. Publish stores it in its own repository, and the Dispatcher caches the rendered response. The flow is:

1. Author edits a page and selects Publish (or uses a workflow that activates it).
2. Replication copies the page to publish.
3. The next request for the page reaches publish, which renders it and returns the response.
4. The Dispatcher caches the response according to its rules, and the CDN caches it according to the headers it receives.

Note:- Replication details, including activation of assets and the cache flush calls, depend on your configuration. Check the replication settings in your environment before you assume a specific behaviour.

How code flows through Cloud Manager

Code and configuration never go directly to the author or publish tiers from your laptop. They travel through Cloud Manager:

1. You push to the Git repository connected to your program.
2. A full-stack pipeline builds the project, runs the tests and quality gates, and produces the deployable artifacts.
3. The pipeline deploys to a non-production environment first, then to production when you approve it.
4. Not all configuration travels the same way. OSGi configurations ship with your code in the full-stack pipeline. Dispatcher configuration ships with the full-stack pipeline, or on its own through a web tier config pipeline. CDN rules, purge keys and log forwarding ship through a separate config pipeline.

A config pipeline reads YAML files from a config folder in your repository. The following cdn.yaml declares the purge keys used later in this lesson for the production environment. The ${{...}} values are Cloud Manager secret environment variables, so the keys never appear in Git.

kind: "CDN"
version: "1"
metadata:
  envTypes: ["prod"]
data:
  authentication:
    authenticators:
      - name: purge-auth
        type: purge
        purgeKey1: ${{CDN_PURGEKEY_031224}}
        purgeKey2: ${{CDN_PURGEKEY_021225}}
    rules:
      - name: purge-auth-rule
        when: { reqProperty: tier, equals: "publish" }
        action:
          type: authenticate
          authenticator: purge-auth

Run yq cdn.yaml locally to confirm the file is valid YAML before you commit it. Config pipelines validate the file again in Cloud Manager, so a local check only saves you a failed run.

Caching at the Dispatcher and the CDN

Two caches sit in front of publish, and they behave differently.

• Dispatcher cache: files written to disk by the Dispatcher module. It is refreshed when pages are republished and is cleared and refreshed with each deployment. Its Apache layer also adds a default Cache-Control header of five minutes to HTML and text responses.
• CDN cache: a shared cache at the edge. It follows the Cache-Control, Surrogate-Control or Expires header from the origin, so HTML and text are cached for five minutes by default. Responses marked private, no-cache or no-store, or that set a cookie, are not cached.

Invalidation is the part to plan. A content change reaches the browser only when both caches expire or are purged. The Adobe CDN has a purge API that accepts a single URL, a surrogate key or a full purge. Each call uses the PURGE method and an X-AEM-Purge-Key header holding a key you declared in the config pipeline. Use purge for content you need to appear immediately, and rely on time to live for everything else. A hard or full purge sends more traffic to publish, so purge as narrowly as you can.

Hands-on: trace a request with curl

You can see the layers in action without any access to the Dispatcher. Use a public URL on a production or stage environment you are allowed to test against. Replace the example hostname with your own.

Step 1: Request the page and read the headers

curl -sI https://www.mysite.example/content/mysite/en/home.html

Look at Cache-Control for the time to live, Age for how long the response has been cached, and any Server or vendor headers the CDN adds. Run the same request twice. If Age grows between calls, you are reading from a cache rather than from publish.

Step 2: Get past the caches for one request

curl -sI "https://www.mysite.example/content/mysite/en/home.html?cb=$(date +%s)"

The CDN cache key includes the full URL with its query string, so a unique cb value always misses the CDN cache. The Dispatcher does not cache requests with query strings it is not told to ignore, so the request reaches publish. Quote the URL so your shell does not treat ? as a wildcard. Use this to compare responses, not as a fix for stale content.

Step 3: Confirm the page exists on publish

Request the same path on the publish-p<program>-e<env>.adobeaemcloud.com URL from your environment details, and compare the status code and body length. This URL still passes through the Adobe CDN and the Dispatcher, so it does not skip caching. It rules out your custom domain, its DNS and any CDN you run in front of Adobe. If the publish URL returns the page and your domain does not, check the domain mapping, the CDN rules and the virtual host that matches your domain.

Step 4: Confirm the Dispatcher allows the path

If the page exists on author and is published, but every request returns a 403 or 404, check the Dispatcher filter rules. Filters are the most common reason a valid request does not reach publish.

Hands-on: read the Dispatcher configuration

The Dispatcher configuration lives in your repository, in the dispatcher/src folder. The flexible mode layout lets you edit the files that matter and leaves Adobe-managed defaults alone. Custom filters go in conf.dispatcher.d/filters/filters.any. That file starts by including Adobe’s default_filters.any, which denies everything and then allows normal page, image and client library requests. You add only what your project needs after the include.

Step 5: Review the filter rules

$include "./default_filters.any"

# Project addition: the site search JSON servlet only
/0200 { /type "allow" /method "GET" /path "/content/mysite/*" /selectors "search" /extension "json" }

When several filters match a request, the last matching rule wins. The defaults start with deny-all, so each allow you add after the include opens only what it names. Keep the rules narrow and use a name that does not clash with the default rules. A broad allow such as /url "/content/*" placed here would reopen selectors and extensions that the defaults deny.

Step 6: Validate before you deploy

Run the Dispatcher SDK validator before you push. Run it from the folder where you extracted the Dispatcher SDK, and pass the path to your project’s dispatcher/src folder. Docker must be running for the second phase. The validator runs in three phases: a rules check, an Apache syntax check in Docker, and an immutability check that catches edits to files Adobe manages.

cd ~/aem-sdk/dispatcher-sdk
./bin/validate.sh ~/projects/mysite/dispatcher/src

If the immutability check fails, revert the change to the Adobe-managed file. Do not commit a fork of a file you are not allowed to edit.

Where each concern lives

Troubleshooting table

Hands-on challenge

On a non-production environment, pick one public page. Record its Cache-Control and Age values from the public host and from the publish host. Activate a small text change on the author, wait for it to replicate, then repeat the requests. Write down which layer served each response before and after the change, and how long it took for the public host to show the new content.

Key takeaways

✅ The request path is browser, CDN, Dispatcher, then publish. Debug from the outside in.
✅ Publishing copies content. Code changes need a Cloud Manager deployment.
✅ The Dispatcher cache is cleared and refreshed with each deployment.
✅ The CDN follows the cache headers it receives. HTML defaults to five minutes. Use the purge API for urgent changes.
✅ The last matching filter wins. Keep Adobe’s defaults first, add narrow allows after them, and validate before you push.

Knowledge check

Frequently asked questions

Continue your learning

• Previous lesson: Lesson 01, AEM as a Cloud Service Overview for Developers, with the course roadmap at /aem-cloud/.
• Next lesson: Lesson 04, Set Up AEMaaCS Local Development Environment (unpublished draft; see the roadmap).
• Practice quiz: AEM Cloud Service practice test 1.
• Dispatcher background: Dispatcher setup for AEM 6.x.
• Roadmap: AEM as a Cloud Service learning roadmap.