Org Skills

Dispatcher flexible mode — file layout, immutable files, local validation

Supporting material for aem-dispatcher. Agents load it on demand; it ships inside the skill folder.

RawSource

Verified: 2026-09 against https://experienceleague.adobe.com/en/docs/experience-manager-cloud-service/content/implementing/dispatcher/disp-overview

Open this when creating a dispatcher module, adding a site, fixing a validator failure, or wondering which file you are allowed to edit.

Layout

dispatcher/src/
├── opt-in/USE_SOURCES_DIRECTLY          ← presence of this file enables flexible mode
├── conf.d/                              ← Apache httpd
│   ├── available_vhosts/<site>.vhost
│   ├── enabled_vhosts/<site>.vhost      ← relative symlink → ../available_vhosts/<site>.vhost
│   ├── rewrites/rewrite.rules           ← mod_rewrite rules, included from the vhost
│   └── variables/
│       ├── custom.vars                  ← your Define directives
│       └── global.vars                  ← product variables you may override (see below)
└── conf.dispatcher.d/                   ← dispatcher module
    ├── available_farms/<site>.farm
    ├── enabled_farms/<site>.farm        ← relative symlink → ../available_farms/<site>.farm
    ├── filters/filters.any              ← $include "../filters/default_filters.any" + your allows
    ├── cache/rules.any
    ├── clientheaders/clientheaders.any
    ├── virtualhosts/virtualhosts.any
    └── renders/                         ← Adobe-managed; the publish render is injected
  • Both enabled_* entries must be relative symlinks. A Windows checkout that turns them into text files deploys a farm that matches nothing; check with ls -l before committing.
  • One farm per site or per hostname group. Farms are matched top to bottom by /virtualhosts, so order the specific ones first.

Files you may not change

The pipeline rejects or overwrites edits to:

default_filters.any, default_rules.any, default_invalidate.any, default_clientheaders.any, default_virtualhosts.any, default_renders.any, default.farm, default.vhost, dispatcher.any, dispatcher_vhost.conf, and the Apache base configuration.

Extend them instead:

/filters {
  $include "../filters/default_filters.any"
  /0100 { /type "allow" /method "GET" /path "/content/acme/*" /extension "html" }
}

The deny-all rule is already in default_filters.any — adding your own /0001 { /type "deny" /url "*" } duplicates it and makes the numbering harder to reason about.

global.vars flags worth knowing

conf.d/variables/global.vars is one of the product files you may copy and override. The flags that change behaviour:

Variable Effect
CACHE_GRAPHQL_PERSISTED_QUERIES Lets the dispatcher cache /graphql/execute.json responses. Without it, persisted queries are never cached at the dispatcher tier
DISABLE_DEFAULT_REWRITES / DISABLE_DEFAULT_VHOSTS Turn off Adobe's default rewrite and vhost includes when you provide your own
FORWARDED_HOST_SETTING How the X-Forwarded-Host header is trusted; relevant behind a BYO CDN

Also set FileETag Digest in the vhost when you want stable ETags across pods — the default inode-based ETag differs per container and breaks conditional requests.

Environment differences

Use Apache variables, never per-environment copies of a file:

<IfDefine ENVIRONMENT_DEV>
  Define STRICT_SECURITY_OFF
</IfDefine>
Define CONTENT_FOLDER_NAME acme

ENVIRONMENT_DEV, ENVIRONMENT_STAGE and ENVIRONMENT_PROD are defined by the platform.

Validate before every commit

# from the dispatcher SDK
./bin/validate.sh ./src
./bin/docker_run.sh ./src host.docker.internal:4503 8080
  • validate.sh checks syntax, immutable-file edits and the allowed Apache directive list — the same check the web-tier pipeline runs, so a green local run means a green pipeline step.
  • docker_run.sh starts Apache + dispatcher against your local publish SDK. Set DISP_LOG_LEVEL=trace1 for full cache and filter decisions, and send X-Dispatcher-Info: true on a request to get the decision back in the response headers.

AEM 6.5

The same principles apply, but you own dispatcher.any and the whole Apache build, there is no validate.sh, and cache invalidation comes from flush replication agents on publish calling /dispatcher/invalidate.cache rather than from content distribution.