Dispatcher Tips and Tricks on AEM as a Cloud Service

Damian Langsweirdt
Jan 27 · 4 min read

Content delivery using Adobe Experience Manager (AEM) has long been aided by the dispatcher module, which sits in between visitors to a website and AEM itself to help with caching, URL rewriting, HTTP header manipulation and more. Those benefits generally carry over from the traditional AEM platform to AEM as a Cloud Service, however as a member of the Cloud Service engineering team at Adobe I wanted to share some insights to best take advantage of the power of the dispatcher on Cloud Service based on learnings from real customer implementations.

Tip #1 — Use the local dispatcher validator

One difference with Cloud Service is the requirement that all dispatcher configuration is treated as code stored in git, and deployed via the standard Cloud Manager CI/CD pipeline. A side of effect of this difference is that small, iterative changes made during development require a more time-consuming deployment, right? Not necessarily! See the documentation which describes how much of the changes can be validated and tested locally without requiring a cloud deployment.

One common issue this best practice can help identify is missing certain required symbolic links. Whether via quick local validation (recommended) or more time-consuming failed cloud deployment, if you see an error message like below it means you should look into missing symbolic links from the enabled_ folders to the available_ folders:

Dispatcher configuration validation failed: conf.dispatcher.d/enabled_farms/<file>.farm:1: extra characters following label “/<file>.farm” are ignored

Tip #2 — Mind the requirements of product functional tests

A common dispatcher pattern we see across customers is to shorten the length of the URL for readability, branding, or SEO purposes. This could include removing the /content/<site> path prefix or the .html extension of a page. This is a perfectly fine approach, but there are considerations when designing for Cloud Service.

As part of each production pipeline execution, a suite of product tests is run on the Stage environment after it is built. These tests ensure certain basic functionality works, such as page creation and replication, by creating dummy content in the /content/test-site folder. We’ve seen several cases of the URL shortening logic interfere with delivery of /content/test-site, such that the dispatcher rewrites a test page URL to a different folder which returns a 404 and fails a test (and therefore a pipeline execution). Please ensure the /content/test-site folder is not adjusted via rewrite rules.

A less common but equally impactful scenario is when a custom 404 page is delivered with a 200 HTTP status code. The product tests expect a 404 status code after unpublishing test content, so please ensure the status code is not incorrectly manipulated in the dispatcher or elsewhere.

Tip #3 — Review the virtual host configuration carefully

A misconfigured virtual host can ironically show a default Apache message “It works!” when in fact you might be thinking the opposite! These “It works!” messages can be seen via browser, in Cloud Manager log files during a failed pipeline execution, in log files of AEM, or even by an internal Adobe team responsible for validating each product release update against cloned customer environments before the update is pushed to customers.

The easiest (and default) solution is to include ServerAlias * in your virtual host file in the /dispatcher/src/conf.d/available_vhostsfolder. This will permit the host aliases used by product functional tests, dispatcher cache invalidation, and clones to function. There may be a temptation to restrict the allowed ServerAlias list in the name of security or simply due to “that’s how we’ve always done it” which was carried over during a migration exercise, however if ServerAlias * is not acceptable, at a minimum the following ServerAlias entries must be allowed in addition to your custom domains: localhost, publish*.adobeaemcloud.net, and publish*.adobeaemcloud.com.

Shameless plug: check out this Medium article on dispatcher migration from my colleague James Talbot!

Tip #4 — Take advantage of the CDN

One of the great benefits of Cloud Service is the presence of a CDN to allow content to be cached at points of presence around the globe to reduce network latency and speed up page delivery. The key is to configure the dispatcher to maximize this benefit. By default, html pages are cached at the CDN for 5 minutes, and clientlibs much longer. Assets are NOT cached at the CDN by default, so if you want your images to be served as quickly as possible, see this page on our documentation.

Incorporating the above into your development process should help streamline your effort and eliminate common pitfalls on the AEM as a Cloud Service platform. Happy dispatching!

Adobe Tech Blog

News, updates, and thoughts related to Adobe, developers…