Setting Up A Local AEM Dispatcher With Docker

Reverse proxy and caching are two of the many features provided by the AEM dispatcher module. It is the prism through which your web users will view content on the AEM publisher. Developers will say the development and operations (DevOps) team handles it. DevOps rely on developers to provide instructions on how to configure it. Hardly anyone sets it up in their local environment. Instead, they depend on remote systems to test and debug. This can sometimes turn into a game of whack-a-mole until things work. 

In this post, I will review how to set up a local dispatcher using docker to proxy to your local AEM publish instance. We will be able to update config files, trace logs, and debug. When we send the configuration to DevOps, it will be with an “it worked on my computer” stamp of approval. 

Install Docker 

We leverage Docker to avoid the difficulties that come with installing Apache on your platform (Windows or macOS). We are also getting an environment that is pretty close to what AMS would be using. Installing Docker on your platform should be fairly straight forward. Once installed, you can verify with the following commands

Create an Archetype Project 

You may have your own Apache configuration. Before you throw those in, let’s build a baseline using the archetype project. Note that the aemVersion is set to 6.5.0 which is NOT the same if you were using AEM as a cloud service. This means that they will work on AMS dispatchers, not AEM as a Cloud Service.

mvn -B archetype:generate \
 -D archetypeGroupId=com.adobe.aem \
 -D archetypeArtifactId=aem-project-archetype \
 -D archetypeVersion=24 \
 -D appTitle="My Site" \
 -D appId="mysite" \
 -D groupId="com.mysite" \
 -D aemVersion="6.5.0"

Building an Image 

To build an image, we are going to leverage an existing CentOS image. We will install Apache and the dispatcher module. This is pretty much the same setup on AMS. The only difference is that they use the Enterprise RedHat Linux which CentOS is the free version of. First, create the following Dockerfile within the mysite project folder: 

FROM centos:7.8.2003
ARG MODULE_URL

RUN yum -y update && \
    yum -y install httpd && \
    yum clean all && \
    mv $(curl --insecure --silent ${MODULE_URL} | \
    tar xzvf - --wildcards "*.so" | head -1) /etc/httpd/modules/mod_dispatcher.so && \
    chown root:root /etc/httpd/modules/mod_dispatcher.so

EXPOSE 80

RUN mkdir -p /mnt/var/www/author && \
    mkdir -p /mnt/var/www/html && \
    mkdir -p /mnt/var/www/default && \
    chown -R apache:apache /mnt/var/www

WORKDIR /etc/httpd
CMD [ "apachectl", "-DFOREGROUND" ]

Inspired Digital Experiences for Manufacturing & Automotive

Whether you’re just beginning your digital transformation journey or are well on your way, we invite you to explore our partnership with Adobe and our diverse capabilities in manufacturing and automotive.

Download Lookbook

Now, we build the image with the following command within the mysite project folder: 

docker build \
    -t mysite/dispatcher:latest \
    --build-arg MODULE_URL=https://download.macromedia.com/dispatcher/download/dispatcher-apache2.4-linux-x86_64-4.3.3.tar.gz \
    .

Creating a Container 

Next, you will need to create a container using the image by leveraging Docker Compose. Create a file called docker-compose.yml within the mysite folder. 

version: "3.8"

services:

  dispatcher:
    image: mysite/dispatcher:latest
    ports:
        - 80:80
    environment:
      DISP_ID: dispatcher1docker
      AUTHOR_DEFAULT_HOSTNAME: author.mycompany.local
      AUTHOR_IP: host.docker.internal
      AUTHOR_PORT: 4502
      AUTHOR_DOCROOT: /mnt/var/www/author
      PUBLISH_DEFAULT_HOSTNAME: mysite.mycompany.local
      PUBLISH_IP: host.docker.internal
      PUBLISH_PORT: 4503
      PUBLISH_DOCROOT: /mnt/var/www/html
      CRX_FILTER: deny
    volumes:
      - ./dispatcher/src/conf:/etc/httpd/conf:ro
      - ./dispatcher/src/conf.d:/etc/httpd/conf.d:ro
      - ./dispatcher/src/conf.dispatcher.d:/etc/httpd/conf.dispatcher.d:ro
      - ./dispatcher/src/conf.modules.d:/etc/httpd/conf.modules.d:ro
      - ./httpd-docroot:/mnt/var/www/html

What we are setting up here is a service called dispatcher. The environment variables represent the minimal set used by the archetype Apache configs. The volumes section maps each config folder to its place within the container. The last volume maps the HTML folder where the dispatcher is caching pages to our host’s directory. This is how they will persist should the container restart. It also allows us to navigate the cached data within our host’s file system. 

The archetype configs will create 2 vhosts. They are author.mycompany.local and mysite.mycompany.local. To access these locally, you should make sure to update your hosts file (i.e. /etc/hosts in macOS) so that they resolve to 127.0.0.1. 

Testing MySite Through the Default Dispatcher 

Start your publisher and deploy mysite by using the command we all know and love: 

mvn clean install -P autoInstallPackagePublish -P adobe-public

Start the dispatcher 

docker-compose up -d

And verify the following things 

• You can access mysite directly on the publisher: http://localhost:4503/content/mysite/us/en.html 
• You can access mysite through the dispatcher: http://mysite.mycompany.local/content/mysite/us/en.html 
• You are seeing things getting cached in the mapped folder, in our case httpd-docroot 

Things to Try Out 

There are many dispatcher related topics we could touch upon that would not fit into this tutorial. Here are a few ideas you can try out now that you have a working dispatcher. 

• Test the dispatcher flush 
• Remove the /content/mysite root by updating the rewrite rules 
• Create a new vhost for a new site 
• Access the author through the dispatcher 
• Set up Sling Server Side Includes 
• Tail the logs generated by Apache 
• Explore the modules under /etc/httpd/modules 

I hope you found this blog post useful. For any additional questions, please comment below and be sure to check out our other Adobe blogs.