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.