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

> **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:

```apache
<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

```bash
# 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.
