AEM Dispatcher CentOS Virtual Machine Setup

How to setup AEM Dispatcher on a CentOS Virtual Machine (VM) alongside Author and Publish instances. This solution gives an Adobe Experience Manager developer a complete end-to-end environment for local AEM development.

For this CentOS VM, I downloaded the Minimal ISO from The ISO filename was CentOS-7-x86_64-Minimal-1810.iso at the time of this writing.

Create your VM using the Virtual Machine program you prefer. Popular options are VirtualBox, VMware or Hyper-V (Windows only).

Here are the virtual hardware settings I used when creating the VM.

  • 4 GB Memory
  • 32 GB max disk size

I’m not going to go over the entire CentOS 7 installation, however, I would like to highlight a couple setup items during the installation process. These items pertain to a local VM that is only accessible from within the host computer network.

On the CentOS Installation Summary screen, select Security Policy.

Security Policy selected on CentOS 7 Installation Summary screen
Security Policy selected

On the CentOS Installation Security Policy screen, toggle the security policy switch to off.

Apply security policy toggled off on CentOS 7 Installation Security Policy screen
Security Policy - Apply security policy: Off

Additionally, I did not create a user and only set a root password.

These were done to alleviate potential access and permissions issues that I did not want to have to workaround.

The OpenSSH server was already up running on my new minimal CentOS VM. Obtain the IP that your network has assigned the VM and use the terminal to ssh into it for the remainder. e.g.,

ssh root@

Update currently installed packages.

yum update


Since we’re on a local VM, we do not need a firewall. Disable the firewall to prevent complications and free up any system resources under its consumption.

Check the status of the firewall.

firewall-cmd --state

Stop the firewalld service for the current session.

systemctl stop firewalld

Prevent the firewalld service from re-starting on system reboot.

systemctl disable firewalld


Install Java.

yum install java-1.8.0-openjdk


Install Apache.

yum install httpd

Check if Apache is running.

systemctl status httpd

Start Apache as needed.

systemctl start httpd

Create a very basic Hello World index.html page in the /var/www/html directory to verify the Apache default web server is accessible in a web browser.

To transfer files between the host and VM, I’m using the FileZilla client on the host. A connection to the VM is set using the sftp ssh file transfer protocol.

FileZilla site manager with sftp ssh file transfer protocol selected
FileZilla client - Site Manager

Load the page in a web browser using the IP address of the VM. e.g.,


Now we can proceed with the installation of the author, publish and dispatcher instances in the CentOS 7 server VM.

These steps presume that you have an AEM Quickstart jar and respective file from Adobe. If you’re an Adobe Solution Partner, you may visit the AEM Request Page to obtain the necessary files.

Create directory structure for aem author and publish instances.

mkdir -p /opt/aem/{author,publish}

Upload AEM Quickstart jar and files to /opt/aem/author and /opt/aem/publish folders. Set the port number by renaming the Quickstart jar files. e.g.,

cd /opt/aem/author
mv AEM_6.4_Quickstart.jar cq5-author-p4502.jar

cd /opt/aem/publish
mv AEM_6.4_Quickstart.jar cq5-publish-p4503.jar

Unpack the renamed jar files. e.g.,

cd /opt/aem/author
java -jar cq5-author-p4502.jar -unpack

cd /opt/aem/publish
java -jar cq5-publish-p4503.jar -unpack

Every AEM instance is an author instance by default. To configure the publish instance, set CQ_PORT=4503 and CQ_RUNMODE='publish' in the /opt/aem/publish/crx-quickstart/bin/start bash script. e.g.,


# TCP port used for stop and status scripts
if [ -z "$CQ_PORT" ]; then


# runmode(s)
# will not be used if repository is already present
if [ -z "$CQ_RUNMODE" ]; then

Start the publish instance for the first time

java -jar /opt/aem/publish/cq5-publish-p4503.jar -r publish

After a few minutes and everything has initialized, load the publish instance in a browser. e.g.,

After the initial startup of the publish instance, use the stop and start bash scripts from here on out for stopping and starting the instances. e.g.,

bash /opt/aem/publish/crx-quickstart/bin/stop

bash /opt/aem/publish/crx-quickstart/bin/start

Start the author instance.

bash /opt/aem/author/crx-quickstart/bin/start

After a few minutes and everything has initialized, load the author instance in a browser. e.g., The default username and password is admin.


Disable SELinux (Security Enhanced Linux). If enabled, SELinux may cause some errors while running AEM Dispatcher.

Edit /etc/selinux/config


Verify with setsebool

/usr/sbin/setsebool httpd_can_network_connect true

# expected output
setsebool:  SELinux is disabled.

Get the Apache version.

httpd -version

Download Dispatcher for the correct version of Apache and CentOS Linux, e.g.,

# navigate to the root folder
cd /root

# create a dispatcher folder
mkdir dispatcher

# download into the dispatcher folder
curl -L -o dispatcher/dispatcher-apache2.4-linux-x86-64-4.2.3.tar.gz

Extract the tarball into the dispatcher directory, e.g.,

cd /root/dispatcher

tar -xvf dispatcher-apache2.4-linux-x86-64-4.2.3.tar.gz

Create a softlink of the DSO file in the modules directory of Apache, e.g.,

ln -s /root/dispatcher/ /etc/httpd/modules/

Copy `dispatcher.any` file into Apache conf folder.

cp /root/dispatcher/dispatcher.any /etc/httpd/conf/dispatcher.any

Edit the Apache configuration, /etc/httpd/conf/httpd.conf.

  • Load module: load dispatcher_module on start-up
  • Add dispatcher configuration entries
  • SetHandler: activate dispatcher
  • ModMimeUsePathInfo: modify the behavior of mod_mime

Insert the following code somewhere after Include conf.modules.d/*.conf. e.g., after last existing </IfModule>


LoadModule dispatcher_module /etc/httpd/modules/

<IfModule disp_apache2.c>
    DispatcherConfig conf/dispatcher.any
    DispatcherLog logs/dispatcher.log
    DispatcherLogLevel 3
    DispatcherNoServerHeader 0
    DispatcherDeclineRoot 0
    DispatcherUseProcessedURL 0
    DispatcherPassError 0
    DispatcherKeepAliveTimeout 60

    RewriteEngine on
    RewriteRule ^/$ /content/we-retail.html [R]

<Directory />
<IfModule disp_apache2.c>
    SetHandler dispatcher-handler
Options FollowSymLinks
AllowOverride None
<Directory />
<IfModule disp_apache2.c>
    SetHandler dispatcher-handler
    ModMimeUsePathInfo On
Options FollowSymLinks
AllowOverride None
  • The RewriteRule in the configuration above simply redirects the web root to the we-retail content. For multiple sites, you can define virtual hosts. For more info, checkout the AEM Dispatcher Guide: Using Dispatcher with Multiple Domains.

Edit /etc/httpd/conf/dispatcher.any.


/virtualhosts {
/renders {
    /rend01 {
        # Hostname or IP of the render
        /hostname ""
        # Port of the render
        /port "4503”

This configuration accepts all requests on port 80 and serves the pages provided by the publish instance on port 4503.

Restart Apache after configuration changes.

systemctl restart httpd

Load the dispatcher instance in a browser. e.g.,


comments powered by Disqus