Multiple AEM Sites on a Local Dispatcher

The dispatcher is an integral part of the AEM architecture. So important that it has made it into AEMaaCS. But it is simple and has not changed in a long time. In fact, I'm surprised it has even lasted this long. Its basic core functions are caching and filtering! Couldn't we do that with an Nginx module? Or a Traefik plugin? I'm willing to bet that in the years to come, it will get phased out in AEMaaCS. In favor of a more managed solution.

What has improved is the tooling provided by Adobe. When I first started on AEM, I remember setting up Apache on my MacBook. Ewww... Then I set it up on Vagrant. Then Docker. But with AEMaaCS, the tools are there for you already.

Before you can start spinning out sites, you will need two things. The dispatcher tools. And a working validation script.

Set up local Dispatcher Tools

This is already well documented. So I will not get into much detail. The gist of it is that once you finish, the tools directory is somewhere on your local machine. And the bin folder got added to the PATH environment variable. For example here is a short script I would use on a MackBook

unzip aem-sdk-xxx.zip
chmod a+x aem-sdk-dispatcher-tools-x.x.x-unix.sh 
./aem-sdk-dispatcher-tools-x.x.x-unix.sh
mkdir -p ~/aem-sdk
mv dispatcher-sdk-x.x.x ~/aem-sdk/dispatcher
export PATH=$PATH:~/aem-sdk/dispatcher/bin

Validating Dispatcher Configuration

You generated an AEM project using the archetype. Within the project you will find a dispatcher maven module. The Cloud Manager will deploy the package generated by dispatcher/pom.xml.

To avoid delays, It is a good practice to validate the changes made before committing them to GIT. The problem is that the files may not match the version of the dispatcher tools you are using. Again, this is well documented here. You need to update the baseline by running the update_sdk.sh script. It will need to know two things, the path to the dispatcher tools. And the path to the dispatcher configurations. Within the dispatcher directory run

./update_sdk.sh ~/aem-sdk/dispatcher src

The update process will change the immutable files. And their checksum in dispatcher/pom.xml. Commit these changes to GIT.

Now you can validate the dispatcher configuration. Within the dispatcher directory run this command to validate the src configuration directory

~/aem-sdk/dispatcher/bin/validate.sh src

Run the Local Dispatcher

Now you can start the dispatcher. The basic command needs three arguments.

• The configuration folder. In our case, src. This folder will get mapped to a Docker volume. That will be Apache's configuration directory.

• The URL to the publish instance. It can be local or remote. In this case host.docker.internal:4503 is the URL available within the Docker container. That points to the publish running on the local machine.

• The port the container will expose, in this case 80. This container will map this port to Apache's own port, that is always 80.

If you have installed the default content generated by the archetype, you should now be able to load http://localhost/content/mysite/us/en.html. You will also see content getting cached under dispatcher/cache/html. If you do not, you are logged in via Sling. And the dispatcher will not cache content when a Sling user is logged in.

There are useful environment variables. To get the usage instructions run the docker_run.sh without any parameters.

Some Bits of Advice

Before you start customizing the configurations, I would like to give you a few bits of advice.

First, review the documentation. I would like to point out that the dispatcher in the cloud has a limited set of modules and directives.

Second, read the README.md file. It has information about the structure of the project. Explanation of the files. And a list of the immutable files you are not supposed to change.

Third, is if you are migrating. You may have heard or the dispatcher converter tool. Do not cling to the hope that it will automagically migrate your configuration to the cloud. Your best bet is to suck it up. Review your existing sites. And add them to the new cloud dispatcher configuration structure.

And finally, is to follow the KISS principle. There are a lot of safeguards in place to prevent you from shooting yourself in the foot. So try to stay within the guard rails. And keep things simple.

Come Up With a Naming Convention

You may have seen the WKND site dispatcher configuration. This site is live at https://wknd.site/. The single vHost that is enabled is wkdn.vhost. And it has a catch-all ServerAlias "*". This is fine because the site has only one domain. What if we have multiple site paths and you want to map each to a different domain

• /content/site1 -> www.site1.com

• /content/site2 -> www.site2.com

Or what if you had the single site content, but wanted to slice it by country

• /content/site1/us -> www.site1.us

• /content/site1/pt -> www.site1.pt

There several ways to set up your domains. They key to mapping a domain to a content path is the vHost.

Lets set up our first vHost that will map www.mysite.com -> /content/mysite. You will need an environment naming convention. This is up to you. For example, lets use this

• LOCAL -> dev.mysite.localhost

• DEV -> dev.mysite.com

• QA -> qa.mysite.com

• STAGE -> stage.mysite.com

• PROD -> www.mysite.com

You will need a custom domain setup in Cloud Manager for DEV and up. That is outside the scope of this post. We are focusing on the LOCAL one that uses the .localhost TLD. This should point back to the loopback IP address. And we add this to our first vHost so we can test things on our local machine.

Setup the First vHost

Copy the default.vhost file to a new file www.mysite.com.vhost. Again, use a naming convention that makes sense. In this case I am using the PROD domain name.

Second, enable the site by creating a symlink

❗The 01- prefix will ensure that this file ges processed before the default.vhost. That file has a ServerAlias "*" catch all. The default vHost needs to remain active, and be the last one to get processed.

At a minimum, you will need to change the ServerName & ServerAlias. ServerName has the highest priority. So I will put my PROD host there. Then use the ServerAlias for each lower environment. Also change the value of the X-Vhost. This will come in handy later.

❗Use port 80. In the cloud architecture, the dispatcher is not concerned with TLS termination.

The vHost sets up some other stuff. You may need to change as needed. But the last important piece is the rewrites. You see that it includes rewrite.rules. This file assumes your content got structured in the conventional way: /content/${CONTENT_FOLDER_NAME}. If it is not, you will need to either change this file. Or create a new one and include it. The rewrite rules should translate short URLs to long. For example https://www.mysite.com/us/en.html -> /content/mysite/us/en.html. For more details read the post I wrote a couple of years ago about shortening URLs.

Remember to validate your changes. In case you modified one of the immutable files. Or there are syntax issues.

Now load http://dev.mysite.localhost/. And verify the value of the X-Vhost header. Your domain is now mapped to the site content.

Conclusion

If you are on an AEM 6.5 on-prem setup, you might have gotten used to having direct SSH access to the dispatchers. Where you can make and test your changes. On AEMaaCS, this is not practical. There is no direct access. So you have to wait for the pipeline deployment to complete.

Setting up, validating and testing your vHosts on your localhost will save a lot of time. You will be able to work out complicated rewrite rules. Change the filter rules. Or make other tweaks to the dispatcher farm configuration.