AEM Dispatcher
Created on:
Wednesday, October 10, 2018

How to setup AEM dispatcher

This article is to outline simple stems to setup AEM dispatcher (on Mac, local machine).

Step 1: Getting started

Make sure to install Apache version that is compatible with the available dispatchers for MacOS. Check your Apache version by typing in Terminal: httpd -V

Step 2: Download

Download the right dispatcher version for your MacOS version and your Apache version. Go here to download: https://www.adobeaemcloud.com/content/companies/public/adobe/dispatcher/dispatcher.html

Step 3: Setup virtual hosts

  • Add your host name (i.e. local-aem-publish.webconsol.com) to your hosts file (/etc/hosts for Mac)
  • Add virtual host configuration file: /etc/apache2/extra/local-aem-publish.webconsol.com.conf. See example below.
    <VirtualHost local-aem-publish.webconsol.com:80>
       ServerName local-aem-publish.webconsol.com
       ServerAlias local-aem-publish.webconsol.com
       DocumentRoot "/var/www/webconsol/dispatcher"
       ErrorLog "/var/log/apache2/local-aem-publish.webconsol-error_log"
       CustomLog "/var/log/apache2/local-aem-publish.webconsol-access_log" common
       <Directory "/var/www/webconsol/dispatcher">
           <IfModule disp_apache2.c>
               SetHandler dispatcher-handler
               ModMimeUsePathInfo On
           </IfModule>
           Options FollowSymLinks
           AllowOverride None
           # Apache httpd 2.2
           # Order allow,deny
           # Allow from all
           # Apache httpd 2.4
           Require all granted
       </Directory>
    </VirtualHost>
    <VirtualHost local-aem-publish.webconsol.com:443>
       ServerName local-aem-publish.webconsol.com
       ServerAlias local-aem-publish.webconsol.com
       DocumentRoot "/var/www/webconsol/dispatcher"
       ErrorLog "/var/log/apache2/local-aem-publish.webconsol-error_log"
       CustomLog "/var/log/apache2/local-aem-publish.webconsol-access_log" common
       SSLEngine on
       SSLCipherSuite ALL:!ADH:!EXPORT56:RC4+RSA:+HIGH:+MEDIUM:+LOW:+SSLv2:+EXP:+eNULL
       SSLCertificateFile /var/www/webconsol/ssl/dev/webconsol.com.crt
       SSLCertificateKeyFile /var/www/webconsol/ssl/dev/webconsol.com.key
       SSLCACertificateFile /var/www/webconsol/ssl/dev/webconsol.bundle.crt
       <Directory "/var/www/webconsol/dispatcher">
           <IfModule disp_apache2.c>
               SetHandler dispatcher-handler
               ModMimeUsePathInfo On
           </IfModule>
           Options FollowSymLinks
           AllowOverride None
           # Apache httpd 2.2
           # Order allow,deny
           # Allow from all
           # Apache httpd 2.4
           Require all granted
       </Directory>
    </VirtualHost>

    NOTE: you might not need the configuration for HTTPS. If you want to test HTTPS, you might want to check on how to generate and setup self-signed SSL certificate here.

Step 4: Install and enable dispatcher

  • Create folder /private/libexec/apache2, if not already exists.
  • Copy the dispatcher module file (i.e. dispatcher-apache2.4-4.2.1.so) to /private/libexec/apache2.
  • Edit httpd.conf to enable the dispatcher Apache module (LoadModule dispatcher_module /private/libexec/apache2/mod_dispatcher.so)
  • Add /etc/apache2/extra/dispatcher.any and add the following configuration code:

    # name of the dispatcher
    /name "internet-server"
    # each farm configures a set off (load balanced) renders
    /farms {
       # first farm entry (label is not important, just for your convenience)
       /website {
           /virtualhosts {
               "local-aem-publish.webconsol.com"
           }
           /renders {
               /0001 {
                   /hostname "127.0.0.1"
                   /port "8000"
               }
           }
           /cache {
               /docroot "/var/www/webconsol/dispatcher"
               /enableTTL "1"
           }
       }
    }
  • Add /etc/apache2/extra/dispatcher.conf and add the following configuration code:

    <IfModule disp_apache2.c>

       # location of the configuration file. eg: 'conf/dispatcher.any'
       DispatcherConfig /etc/apache2/extra/dispatcher.any

       # location of the dispatcher log file. eg: 'logs/dispatcher.log'
       DispatcherLog    /var/www/webconsol/dispatcher/dispatcher.log

       # log level for the dispatcher log, can be either specified
       # as a string or an integer (in parentheses)
       # error(0): Errors
       # warn(1):  Warnings
       # info(2):  Infos
       # debug(3): Debug
       # trace(4): Trace
       # Ensure debug logging is only enabled on development environments as the log files can become large quickly
       DispatcherLogLevel debug

       # if turned on, the dispatcher looks like a normal module
       #DispatcherNoServerHeader Off

       # if turned on, request to / are not handled by the dispatcher
       # use the mod_alias then for the correct mapping
       DispatcherDeclineRoot Off

       # if turned on, the dispatcher uses the URL already processed
       # by handlers preceeding the dispatcher (i.e. mod_rewrite)
       # instead of the original one passed to the web server.
       DispatcherUseProcessedURL On

       # if turned to 1, the dispatcher does not spool an error
       # response to the client (where the status code is greater
       # or equal than 400), but passes the status code to
       # Apache, which e.g. allows an ErrorDocument directive
       # to process such a status code.
       #
       # Additionally, one can specify the status code ranges that should
       # be left to web server to handle, e.g.
       #
       # DispatcherPassError 400-404,501
       DispatcherPassError 0

       #
       # DispatcherKeepAliveTimeout specifies the number of seconds a
       # connection to a backend should be kept alive. If not set or
       # set to zero, connections are not kept alive.
       #
       #DispatcherKeepAliveTimeout 60

    </IfModule>

Step 5: Restart your Apache or HTTP service: sudo apachectl restart

Recap: at the end of the setups, you should be having the following:

  • Downloaded the right dispatcher (Apache module)
  • Copied the dispatcher apache module to /private/libexec/apache2
  • Added /var/www/webconsol/dispatcher folder.
  • Added /etc/apache2/extra/local-aem-publish.webconsol.com.conf file.
  • Added /etc/apache2/extra/dispatcher.any file.
  • Added /etc/apache2/extra/dispatcher.conf file.
Stop blending in with the rest of the crowd &
start leaving your mark on the web.
Your success is our success

Let's work together