AEM Dispatcher setup for Linux

Installing dispatcher for AEM in Apache Web-server in Linux may get little tricky, as documentation provided by Adobe on Installation of Dispatcher in Linux is not sufficient, and if we take it in analogy and try doing same way we do in Windows, then we face some issues locating the appropriate files.

Prerequisites for Dispatcher Setup

• Apache 2.2 web server – In Ubuntu 12.0 and higher, Apache 2.2 webserver is pre-installed, but in case it is not there, you can find the installation instructions here.
• Dispatcher Module – Appropriate dispatcher module can be downloaded from Adobe Package Share.

Installation Instructions

1. Considering Apache web server is already setup in the system, go ahead and extract dispatcher module using the following command:

    tar -xvzf <dispatcher..xxxx..yyyy.tar.gz>

2. Once you have extracted the files, now you have to move the appropriate files to their respective apt path.
3. Move “dispatcher-apache2.x-4.1.x.so” to “/usr/lib/apache2/modules”. There you will find all the modules already being loaded by apache 2 webserver.
4. Adobe recommends to give a soft name to your dispatcher module, but you don’t need it as once setup is done, you will be hardly using it again.
5. Now go ahead and create a folder conf under “/etc/apache2/”, and move “dispatcher.any” file under this folder. Make sure that you don’t move your dispatcher.any file to ‘conf.d’ folder which is already present.
6. Now is the time to edit and map module file that you added and map the dispatcher.any file. Go ahead and edit apache2.conf file present under “etc/apache2/”.
7. Scroll to the end, put some nice comments about you adding some new configs, and add following:

   LoadModule dispatcher_module /usr/lib/apache2/modules/dispatcher-apache2.2-4.1.5.so
   
   <IfModule disp_apache2.c>
   # location of the configuration file. eg: 'conf/dispatcher.any'
   DispatcherConfig conf/dispatcher.any
   
   # location of the dispatcher log file. eg: 'logs/dispatcher.log'
   DispatcherLog /var/log/apache2/dispatcher.log
   
   # log level for the dispatcher log
   # 0 Errors
   # 1 Warnings
   # 2 Infos
   # 3 Debug
   DispatcherLogLevel 3
   
   # if turned to 1, the dispatcher looks like a normal module
   DispatcherNoServerHeader 0
   
   # if turned to 1, request to / are not handled by the dispatcher
   # use the mod_alias then for the correct mapping
   DispatcherDeclineRoot 0
   
   # if turned to 1, 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 0
   
   # 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.
   DispatcherPassError 0
   </IfModule>
   
   

8. Also add the following config to the end of apache2.conf file, which loads the dispatcher in web-server.

   <Directory />
   
   <IfModule disp_apache2.c> 
   # enable dispatcher for ALL request. if this is too restrictive, 
   # move it to another location
   SetHandler dispatcher-handler
   </IfModule>
   
   Options FollowSymLinks
   AllowOverride None
   
   </Directory>

9. Comments given above are self-explanatory but, you can still go and edit configs if needed as per following descriptions:
   • DispatcherConfig: Location and name of the configuration file (Can be given as an absolute or relative path)
   • DispatcherLog: Location and name of the log file (Can be given as an absolute or relative path)
   • DispatcherLogLevel: Log level for the log file
   • DispatcherNoServerHeader: Whether to use the Apache or CQ server header
   • DispatcherDeclineRoot: Defines whether to decline requests to the root “/”
   • DispatcherUseProcessedURL: Defines whether to use the original request URL or to use one already processed by other handlers (ie: mod_rewrite)
     • Note: This is essential for rewriting incoming links (stripping away the ‘content/{site_name}’)
   • DispatcherPassError: Defines whether CQ or Apache will handle HTTP 40x error codes
   • SetHandler (Apache parameter): Forces all matching files to be processed by a handler
10. Make sure, that path that is provided for load module, matches with the path where you placed your dispatcher module. Also match the name and version of dispatcher module, and change the config as required.
11. Now configure dispatcher.any file. Edit /renders section in dispatcher.any.

    
    /renders
    {
    /rend01
    {
    /hostname "localhost"
    [2]--> /port "80"
    }
    }
    /cache
    {
    /docroot "/var/cache/apache2/<cqcache>"
    }
    

    By default you may find port set to 8000 or 8080, change it to 80.
    Give whatever soft-name you want to give to your cache folder in place of “cqcache”

12. Restart the apache server to let web server take effect. You can restart apache server by using the following command:

    
    sudo /etc/init.d/apache2 restart
    

13. Once the server is restarted and you get [OK] message, go and check /var/log/apache2/dispatcher.log file. If it says dispatcher initialized with correct cache path, it means dispatcher is successfully setup and ready to be used.

Now you just need to configure your CQ replication agent, and point dispatcher flush agents to correct port.

I tested this today itself i.e. 14th Oct 2013 on Ubuntu 13 64 bit debian based OS. It worked like wonder for me. Please post your comments and queries if you have any issues with it, and also if there are better ways to do it. 😉 Cheeeerz.