# Setting Up AEM with Dispatcher on Apache 2.2 (Local Development Environment)

If you're working on AEM Sites or Assets projects, sooner or later you'll need to test caching, URL rewriting, or security filters the way they'll actually behave in production — and that means running a **Dispatcher** in front of your AEM instance, even locally.

This guide walks through setting up the AEM Dispatcher module with **Apache HTTP Server 2.2** on your local machine.

> **Note:** Apache 2.2 reached end-of-life a while back, and most current AEM Dispatcher releases (5.x) are built and tested against Apache 2.4. If you have a choice, prefer Apache 2.4 for new setups. This guide is for cases where you specifically need to replicate an existing 2.2-based environment (e.g., matching a legacy production stack).

## Prerequisites

Before you start, make sure you have:

*   A running local AEM instance (author and/or publish) — typically on port `4502` (author) and `4503` (publish)
    
*   Apache HTTP Server 2.2 installed
    
*   The AEM Dispatcher module package for Apache 2.2 (downloaded from Adobe Software Distribution — you'll need a valid Adobe account with AEM entitlements)
    
*   Basic familiarity with editing `httpd.conf`
    

## Step 1: Verify Your Apache Installation

Confirm Apache 2.2 is installed and check whether it's 32-bit or 64-bit, since the Dispatcher module must match:

```bash
httpd -v
httpd -V | grep -i "architecture"
```

You'll need this info to pick the correct Dispatcher binary in the next step.

## Step 2: Download and Place the Dispatcher Module

From the Dispatcher package you downloaded, locate the module file matching your OS and Apache version:

*   Windows: `dispatcher-apache2.2-x86_64-<version>.so` (or 32-bit equivalent ex: **disp\_apache2.2.dll**)
    
*   Linux: `dispatcher-apache2.2-x86_64-<version>.so`
    
*   macOS: `dispatcher-apache2.2-x86_64-<version>.so`
    

Copy this file into your Apache `modules` directory and rename it for clarity:

```bash
cp dispatcher-apache2.2-x86_64-<version>.so /path/to/apache2.2/modules/mod_dispatcher.so
```

## Step 3: Load the Module in httpd.conf

Open your Apache configuration file (`conf/httpd.conf`) and add the following line, ideally near the other `LoadModule` directives:

```apache
LoadModule dispatcher_module modules/mod_dispatcher.so
```

## Step 4: Create the Dispatcher Configuration Directory

Create a folder to hold your Dispatcher configuration files, e.g.:

```bash
mkdir /path/to/apache2.2/conf/dispatcher
```

Inside this folder, you'll typically create:

*   `dispatcher.any` — main dispatcher config
    
*   `available_farms/` — folder holding one `.any` file per "farm" (site)
    
*   `cache/` — local disk cache directory used by Dispatcher
    

## Step 5: Configure the Dispatcher Module in httpd.conf

Add the following block to `httpd.conf` to point Apache at your Dispatcher config and enable the handler:

```apache
<IfModule disp_apache2.c>
    DispatcherConfig conf/dispatcher/dispatcher.any
    DispatcherLog logs/dispatcher.log
    DispatcherLogLevel 3
    DispatcherNoServerHeader Off
    DispatcherDeclineRoot Off
    DispatcherUseProcessedURL Off
    DispatcherPassError 0
</IfModule>

<LocationMatch "^/(.*)">
    SetHandler dispatcher-handler
</LocationMatch>
```

## Step 6: Create the Main dispatcher.any File

Inside `conf/dispatcher/dispatcher.any`, reference your farm file(s):

```plaintext
/farms
{
  $include "available_farms/*.any"
}
```

## Step 7: Create a Farm Configuration

Create `available_farms/localhost.any` with a basic farm definition pointing to your local AEM publish instance:

```plaintext
/localhost
{
  /clientheaders
  {
    "*"
  }

  /virtualhosts
  {
    "localhost"
  }

  /renders
  {
    /rend01
    {
      /hostname "localhost"
      /port "4503"
    }
  }

  /filter
  {
    /0001 { /type "allow" /glob "*" }
  }

  /cache
  {
    /docroot "/path/to/apache2.2/htdocs"
    /rules
    {
      /0000 { /glob "*" /type "allow" }
    }
    /statfileslevel "3"
    /allowAuthorized "0"
  }

  /statfile "/tmp/dispatcher-localhost.stat"
}
```

> The `/filter` section above is intentionally permissive (`"allow" "*"`) for **local testing only**. Never use an open filter like this in a staging or production environment — always define explicit allow/deny rules based on Adobe's recommended Dispatcher security checklist.

## Step 8: Set Up the Document Root

Make sure the `docroot` path in your farm config exists and matches Apache's `DocumentRoot` directive in `httpd.conf`:

```apache
DocumentRoot "/path/to/apache2.2/htdocs"
<Directory "/path/to/apache2.2/htdocs">
    Options Indexes FollowSymLinks
    AllowOverride None
    Order allow,deny
    Allow from all
</Directory>
```

## Step 9: Set Apache to Listen on the Right Port

By default, Apache listens on port 80. For local testing, this is usually fine, but if port 80 is taken, change it:

```apache
Listen 8080
```

## Step 10: Restart Apache and Test

Restart Apache:

```bash
# Linux/macOS
sudo apachectl restart

# Windows (from Apache bin directory)
httpd.exe -k restart
```

Then hit your site through Apache (not directly through AEM's port):

```plaintext
http://localhost:8080/
```

If everything's wired correctly, you should see your AEM publish instance's content served through Apache/Dispatcher.

## Step 11: Verify Caching Is Working

Check the `docroot` folder you configured — after a successful request, Dispatcher should write a static cached copy of the page (e.g., `.html` file) into that directory. You can also tail the Dispatcher log to confirm requests are being processed:

```bash
tail -f /path/to/apache2.2/logs/dispatcher.log
```

## Common Issues & Fixes

*   **Apache fails to start after adding the module** — Usually an architecture mismatch (32-bit module on a 64-bit Apache, or vice versa). Re-check `httpd -V`.
    
*   **Blank page / 404 through Apache** — Double-check the `/renders` hostname and port match your actual AEM publish instance, and that AEM is running.
    
*   **Nothing gets cached** — Verify the `docroot` path is writable by the user running Apache, and that your `/cache/rules` aren't blocking the request path.
    
*   **Changes to dispatcher.any not taking effect** — Dispatcher config is only re-read on Apache restart, not on every request. Always restart Apache after editing `.any` files.
    

## Wrapping Up

This setup mirrors (at a smaller scale) how AEM Dispatcher works in real deployments — caching pages, applying security filters, and routing requests to the right render instance. Getting comfortable with this locally makes it much easier to debug dispatcher-related issues later in staging or production, where you often don't have direct server access.

In a future post, we'll look at moving this same setup to **Apache 2.4** and comparing the syntax differences in `httpd.conf`, along with a deeper dive into Dispatcher security rules (the `/filter` section) that you should never skip in production.