An accelerated video of setting up AEM Dispatcher on macOS. This walk-through does not address all configurations in Apache HTTPD Web Server or AEM Dispatcher, but rather focuses on the basic configuration to get AEM Dispatcher up and running.

This is an accelerated walk through of setting up AEM Dispatcher on macOS, using the macOS installation of Apache HTTPD Web Server. When installing AEM Dispatcher, always prefer the latest version. AEM Dispatcher versions are agnostic to the AEM version.


At the time of recording (January, 2017) the macOS homebrew install of Apache HTTPD Web Server does NOT work with AEM Dispatcher module due to limitations in how homebrew builds the Apache Portable Runtime (APR) dependency.

  1. Collect Apache HTTPD Web Server install information.

    $ httpd -V
  2. Copy the AEM Dispatcher module file to Apache HTTPD Web Server's libexec folder.

    $ sudo mkdir -p /private/libexec/apache2
    $ sudo cp ~/Downloads/dispatcher-apache2.4-darwin-x86-64-4.2.1/ /private/libexec/apache2/
  3. Update Apache HTTPD Web server's httpd.conf file to include (1) the AEM Dispatcher module (2) the AEM Dispatcher Module configuration and (3) inclusion of vhost configuration files.

    $ sudo vi /private/etc/apache2/httpd.conf
    LoadModule dispatcher_module /private/libexec/apache2/
    <IfModule disp_apache2.c>
        # location of the configuration file. eg: 'conf/dispatcher.any'
        DispatcherConfig /private/etc/apache2/conf/dispatcher.any 
        # location of the dispatcher log file. eg: 'logs/dispatcher.log'
        DispatcherLog    /private/var/log/apache2/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
    Include /private/etc/apache2/vhosts/*.conf
  4. Create a vhost file for your local AEM Publish instance.

    $ sudo mkdir -p /private/etc/apache2/vhosts
    $ sudo cp /private/etc/apache2/extra/httpd-vhosts.conf /private/etc/apache2/vhosts/aem-publish.local.conf
    $ sudo vi /private/etc/apache2/vhosts/aem-publish.local.conf
    <VirtualHost *:80>
    	<Directory /Library/WebServer/docroot/publish>
    		<IfModule disp_apache2.c>
    			SetHandler dispatcher-handler
    			ModMimeUsePathInfo On
        	Options FollowSymLinks
    		AllowOverride None
    		# Apache httpd 2.2
    	    # Order allow,deny
    	    # Allow from all
    		# Apache httpd 2.4
    		Require all granted
        ServerName aem-publish.local
        ServerAlias www.aem-publish.local
        DocumentRoot "/Library/WebServer/docroot/publish"
        ErrorLog "/private/var/log/apache2/aem-publish.local-error_log"
        CustomLog "/private/var/log/apache2/aem-publish.local-access_log" common
  5. Ensure the vhost's docroot exists and is owned by the Apache HTTPD Web Server user.

    $ sudo mkdir -p /Library/WebServer/docroot/publish
    $ sudo chown -R _www:_www /Library/WebServer/docroot
  6. Copy over the sample AEM Publish dispatcher.any file and update it to match your configuration.

    $ sudo mkdir -p /private/etc/apache2/conf 
    $ sudo cp ~/Downloads/dispatcher-apache2.4-darwin-x86-64-4.2.1/conf/dispatcher.any /private/etc/apache2/conf/dispatcher.any
    $ sudo vi /private/etc/apache2/conf/dispatcher.any
    /virtualhosts {
    /renders {
      /rend01 {
        /hostname ""
        /port "4503"
    /cache {
        /docroot "/Library/WebServer/docroot/publish"
        /enableTTL "1"
  7. Ensure your vhost will resolve by adding an entry to /etc/hosts

    $ sudo vi /etc/hosts  aem-publish.local
  8. Test the Apache HTTPD Web Server configuration and if all is OK, restart Apache HTTPD Web Server.

    $ sudo apachectl configtest
    $ sudo apachectl restart
  9. Tail your dispatcher.log and watch for issues such a "Filter rejects" log messages.

    $ tail -f /private/var/log/apache2/dispatcher.log | grep rejects

Supporting materials

This work is licensed under a Creative Commons Attribution-Noncommercial-Share Alike 3.0 Unported License  Twitter™ and Facebook posts are not covered under the terms of Creative Commons.

Legal Notices   |   Online Privacy Policy