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 withls -lbefore 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.shchecks 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.shstarts Apache + dispatcher against your local publish SDK. SetDISP_LOG_LEVEL=trace1for full cache and filter decisions, and sendX-Dispatcher-Info: trueon 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.