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:

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:

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:

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

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:

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

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

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

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:

Listen 8080

Step 10: Restart Apache and Test

Restart Apache:

# 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):

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:

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.