AEM Dispatcher. Part 2: Environment Setup

In this post I have put together detailed instructions on how to setup AEM Dispatcher in a Windows environment. I am an AEM developer (this means a Java developer), so setting up Apache is not something that I do a lot. The instructions below would have saved me a lot of time if I had them handy when first trying to setup a server on my local machine.

For demonstration purposes let’s consider the local environment installation from our “getting started” tutorial. We assume that you already have already installed both AEM author (http://localhost:4502) and a publish (http://localhost:4503) instances. Now you only need a couple more things to get the Dispatcher environment ready:

Select one of the three supported static web servers and install it:
Apache HTTP Server (“httpd”);
Microsoft IIS;
Oracle IPlanet.

Install and enable AEM Dispatcher module (plugin) for the selected static web server.
Static web server installation

For the purposes of this demo, we selected Apache HTTP Server (“httpd”). We assume that your local environment is Windows based. If you have another OS family then installation steps will be quite similar.

The following notes are based on my environment:
Windows 7 Professional SP1 x64 OS;
AEM 6.1 author instance (http://localhost:4502);
AEM 6.1 publish instance (http://localhost:4503).

Important note: before downloading httpd installers you should to check if corresponding dispatcher module exists for the version of your future httpd server. Different dispatcher module versions have been made available by Adobe on this page.

You will note that Windows dispatcher module is available only for apache httpd 2.2 version. You can download it in one of the following archives: dispatcher-apache2.2-windows-x86-4.2.0.zip or dispatcher-apache2.2-windows-x86-ssl-4.2.0.zip.

We will use one of these archives in the next section, which will describe how to enable dispatcher module on a static web server.


We need to install apache httpd version 2.2 for x86 platform because we have a Windows environment and only these dispatcher modules are available for our setup. You will note on the apache httpd download page: https://httpd.apache.org/download.cgi, that “Apache httpd for Microsoft Windows is available from a number of third party vendors”.


This means that you will not find apache httpd binaries for Windows on the httpd apache web site but you can choose one of the third party vendors. Vendors have built such binaries from source code and make them available on their sites.

https://httpd.apache.org/docs/current/platform/windows.html#down


Let choose the first one: ApacheHaus. http://www.apachehaus.com/cgi-bin/download.plx Their binaries have been compiled with Visual Studio:


You can find binaries for Apache 2.2 and notice that binaries for that httpd version have been compiled with Visual Studio 2008 (VC9).


Therefore you also need to get an appropriate Microsoft Visual C++ Redistributable Package (x86):


Ok, finally you have downloaded all necessary installers for apache httpd installation:
“vcredist_x86.exe” - Microsoft Visual C++ 2008 SP1 Redistributable Package (x86);
“httpd-2.2.31-x86-r4.zip” - Apache HTTP Server (“httpd”).

Begin by installing “Microsoft Visual C++ 2008 SP1 Redistributable Package (x86)”. Its installation is trivial and consists of accepting the license agreement and following the wizard steps.

Then extract httpd archive and move the Apache22 folder to the C: drive. Your httpd folder will be C:\Apache22.

Open cmd console and go to C:\Apache22\bin directory.


Then type “httpd” command for starting apache httpd server.


Httpd has been started. You may check its working by typing http://localhost in your browser. If everything is setup correctly you will see the Apache home page.


Press ctrl+c in the cmd-console to stop httpd.

Finally, you have installed your own local apache httpd static web server.
Installation and enabling of AEM Dispatcher module

Download corresponding dispatcher module from this page.


We assume that you have downloaded dispatcher-apache2.2-windows-x86-4.2.0.zip.

Extract disp_apache2.2.dll from the archive and move it to C:\Apache22\modules directory.

Add the following settings at the end of the httpd configuration file C:\Apache22\conf\httpd.conf:

LoadModule dispatcher_module modules\disp_apache2.2.dll

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

<Directory />
  <IfModule disp_apache2.c>
    SetHandler dispatcher-handler
    ModMimeUsePathInfo On
  </IfModule>

  Options FollowSymLinks
  AllowOverride None
</Directory>

The 1st line loads dispatcher module. You must set the correct name of your dispatcher dll. In our case it is modules\disp_apache2.2.dll.

The 2nd “ifmodule” block sets some initial properties for the dispatcher:
DispatcherConfig - set full name of the dispatcher configuration file. In this case we set it to conf/dispatcher.any. You may copy the default dispatcher.any file from the dispatcher archive.
DispatcherLog - set full name of the dispatcher’s log file. It is logs/dispatcher.log in our case.
DispatcherLogLevel - log level for the log file from the most briefly 0 (errors) to the most detailed 3 (debug). We set it to Debug level in this example.
DispatcherUseProcessedURL - defines whether to use pre-processed URLs for all further processing by Dispatcher:
0 - use the original URL passed to the web server.
1 - the dispatcher uses the URL already processed by the handlers that precede the dispatcher (i.e. mod_rewrite) instead of the original URL passed to the web server.

The 3rd “directory” block configures the dispatcher to handle incoming requests for the complete website.

This finally completes all installations for httpd and dispatcher. Restart your httpd server for configuration changes to take effect. If you can see that logs/dispatcher.log appear then httpd server is running and dispatcher module is enabled correctly.

Summary
For setting up your dispatcher environment you have to install the following software:
One of three supported static web servers;
Enable dispatcher module for the selected static web server.

Here are the links where you can find detailed and useful documentation: https://docs.adobe.com/docs/en/dispatcher/disp-install.htmlhttps://docs.adobe.com/docs/en/aem/6-0/deploy/technical-requirements.html#par_title_15