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.

Attention macOS Mojave users

Due to security constraints introduced in macOS Mojave (10.14), the AEM Dispatcher module cannot be loaded via the shipped httpd binary. To work around this issue, a copy of the httpd binary must be copied out, and codesign must be used to remove the signature. 

The steps to achieve this are outlined in Step 1 below (however the video continues to use the shipped binary on a pre-macOS Mojave install).

Setting up AEM Dispatcher on macOS

Note:

The newest, compatible version of AEM Dispatcher should always be used. See the release notes below for critical fixes.


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.

Note:

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. This step is for macOS Mojave users only!

    When using macOS Mojave or later, the httpd binary must be copied out and the code signature removed as Apple's shipped httpd requires httpd modules to be signed (and AEM Dispatcher module is not signed).

    $ mkdir -p ~/Applications/apache2/bin
    $ cp /usr/sbin/httpd ~/Applications/apache2/bin
    $ codesign --remove-signature ~/Applications/apache2/bin/httpd

    Note that apachectl is no longer usable witht his copied binary, and the starting and stopping of the web server must be done via the new binary.

    Starting httpd

    • sudo ~/Applications/apache2/bin/httpd \
        -k start \
        -d ~/Applications/apache2/bin/httpd \
        -f /private/etc/apache2/httpd.conf

    Restarting httpd

    • sudo ~/Applications/apache2/bin/httpd \
        -k restart \
        -d ~/Applications/apache2/bin/httpd \
        -f /private/etc/apache2/httpd.conf

    Stopping httpd

    • sudo ~/Applications/apache2/bin/httpd -k stop
  2. Collect Apache HTTPD Web Server install information.

    $ httpd -V

    macOS Mojave users

    macOS Mojave users run the following command instead.

    $ sudo ~/Applications/apache2/bin/httpd -V
  3. Download the appropriate AEM Dispatcher build.

    Since the recording of this video, newer versions of Dispatcher have been released, so use the latest, and adjust the Dispatcher version numbers in paths/filenames in the instructions accordingly.

    Review the AEM Dispatcher release notes to understand when critical fix versions are released.

  4. 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.3.1/dispatcher-apache2.4-4.3.1.so \
              /private/libexec/apache2/mod_dispatcher.so
  5. 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/mod_dispatcher.so
    
    <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
        # Deprecated
        # 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>
    Include /private/etc/apache2/vhosts/*.conf
    
  6. 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
    		</IfModule>
    		
        	Options FollowSymLinks
    		AllowOverride None
    		
    		# Apache httpd 2.2
    	    # Order allow,deny
    	    # Allow from all
    		
    		# Apache httpd 2.4
    		Require all granted
    	</Directory>
    
        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
    </VirtualHost>
    
  7. 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
  8. 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.3.1/conf/dispatcher.any /private/etc/apache2/conf/dispatcher.any
    $ sudo vi /private/etc/apache2/conf/dispatcher.any
    /virtualhosts {
       "aem-publish.local"
    }
    /renders {
      /rend01 {
        /hostname "127.0.0.1"
        /port "4503"
      }
    }
    /cache {
        /docroot "/Library/WebServer/docroot/publish"
        ...
        /enableTTL "1"
    }
  9. Ensure your vhost will resolve by adding an entry to /etc/hosts

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

    $ sudo apachectl configtest
    $ sudo apachectl restart
    

    macOS Mojave users

    macOS Mojave users run the following commands (not apachectl).

    $ sudo ~/Applications/apache2/bin/httpd -k stop
    $ sudo ~/Applications/apache2/bin/httpd \
      -k start \
      -d ~/Applications/apache2/bin/httpd \
      -f /private/etc/apache2/httpd.conf
    
  11. Ensure AEM Publish is running the host and port configured in the dispatcher.any rend01 (Step 8), and in a new browser tab request:

    Make sure the browser does not automatically switch the request to HTTPS, as this will fail unless HTTPS has been setup on this instance of httpd (out of scope for this tutorial).

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