Surge Migrate

Guide · updated

Dispatcher on AEM as a Cloud Service: conversion, validation and local testing

On AEM 6.5 on-premise or AMS, the Dispatcher configuration is often years of hand edits on a server. On AEM as a Cloud Service it becomes a module in your Git repository, built and deployed by Cloud Manager, and it may only use directives Adobe supports. Converting it is usually a few days of work, but it blocks deployment if it is left to the end.

Flexible mode

Adobe recommends flexible mode, the default for projects from AEM archetype 28 onwards. A project opts in with the file opt-in/USE_SOURCES_DIRECTLY. Legacy mode still exists but expects, among other things, a single rewrite.rules file.

The layout you convert into

  • Apache: conf.d/available_vhosts and conf.d/enabled_vhosts, plus rewrites.
  • Dispatcher: conf.dispatcher.d/available_farms and enabled_farms, plus cache, clientheaders, filters, renders and virtualhosts.
  • The enabled_* folders contain relative symbolic links to files in available_*; do not copy files into them. On Windows, creating the links needs an elevated prompt, WSL or the symlink privilege.

Files you must not change

Adobe ships default files that are immutable in Cloud environments; edits to them are ignored. Include them first and add your rules in your own files next to them. The list includes conf.d/available_vhosts/default.vhost, conf.d/dispatcher_vhost.conf, conf.d/rewrites/default_rewrite.rules, conf.dispatcher.d/available_farms/default.farm, conf.dispatcher.d/dispatcher.any and the default_*.any files for cache, client headers, filters, renders and virtual hosts.

Validate before every commit

The Dispatcher SDK's validate.sh runs three phases:

  1. The Dispatcher validator flags directives that are not allowlisted and checks farm filters for unsafe /glob rules and exposed admin paths.
  2. An httpd -t syntax check starts Apache in Docker (Docker must be installed; AEM does not need to run).
  3. An immutability check confirms the SDK's default files are unchanged.

Add it to your build so a broken configuration never reaches Cloud Manager.

Test locally

The SDK's bin/docker_run.sh starts the Dispatcher in Docker in front of a local publish instance, for example on port 8080 in front of publish on 4503. Set DISP_LOG_LEVEL=Debug for detailed logs; Adobe notes that trace level is not supported in Cloud environments.

Conversion checklist

  1. Inventory every vhost, farm, filter, cache rule, rewrite and header from the 6.5 or AMS servers, including files included from outside the main tree.
  2. Drop rules for paths that no longer exist on Cloud Service (for example /etc design paths moved to /conf or client libraries proxied through /etc.clientlibs).
  3. Recreate the rest in flexible mode on top of the immutable defaults; keep environment differences in variables, not copies.
  4. Move redirects to the CDN or a managed rewrite map where they fit better (see the SEO parity guide).
  5. Run validate.sh and docker_run.sh locally, then deploy to a dev environment and test cache invalidation and headers.

Sources