AEM Dispatcher: Setup, Code Flow, and Variable Utilization

Ready to explore Adobe Experience Manager (AEM) Dispatcher’s secrets? We’ll kick off with an easy setup, then uncover how to smoothly manage farm files in requests. Plus, we’ll show you the magic of using variables for flexible settings. Get ready to dive into Dispatcher’s world of setup, farm files, and smart configurations!

Please note, all commands shared are for Windows machine. For equivalents on other platforms, please refer to link

Pre-requisites:

1. Download latest cloud SDK from Adobe Software distribution
2. Set up AEM publish instance on-local. Install WKND site, if you do not have sample content
3. Install latest Docker Desktop

Important files locations of a dispatcher:

• Cache :
  • defined by: /docroot property in farm file
  • default location for AEMaaCS SDK’s docker image: /mnt/var/www/html
• Logs:
  • default location for AEMaaCS SDK’s docker image: /etc/httpd/logs

Setting-up dispatcher:

1. Create a directory to set up dispatcher (Lets call it sdk-dispatcher)
2. Extract aem-sdk-dispatcher-tools-x.x.x-windows.zip in the sdk-dispatcher directory. It should look like this

Run dispatcher

1. Assure that Docker desktop is running
2. Execute the following command inside sdk-dispatcher folder

bin\docker_run src localhost:4503 8080

The command’s syntax is

$ bin\docker_run <src-folder> <aem-publish-host>:<aem-publish-port> <dispatcher-port>

By default, http://localhost:8080/ will take us to http://localhost:8080/content.html. Use path of a complete page on publish, to validate if the page renders via dispatcher. Example: http://localhost:8080/content/wknd/language-masters/en.html

Possible issue:

If you encounter message like “Sleeping for 5s to wait until port 4503 on localhost is available“, then

1. Go-to command prompt
2. Type ipconfig
3. Copy the value against “IPv4 Address.”
4. Restart the dispatcher with command

$ bin\docker_run <src-folder> <IPv4 Address>:<aem-publish-port> <dispatcher-port>

Try accessing dispatcher now.

Navigating Request Routing and Farm Resolution in AEM

In the midst of growing online interactions, it’s crucial to grasp how the Dispatcher skillfully manages requests and organizes farms. This knowledge ensures smooth and effortless web experiences.

1. Incoming Request Reception:
Upon receiving an incoming request to a website, it is promptly intercepted by the Adobe Experience Manager (AEM) Dispatcher—a key component akin to a vigilant gatekeeper.

2. Virtual Host Matching:
The Dispatcher diligently scrutinizes the request’s URL to ascertain the specific virtual host associated with the request. This virtual host serves as a distinct entrance to the website, akin to a designated gateway.

3. Determining the Appropriate Farm:
After virtual host identification, the Dispatcher endeavors to select the most appropriate farm to handle the request. A farm here refers to a defined cluster or grouping of AEM instances, each with a specific purpose and configuration.

4. Execution of Farm-Level Configurations:
Within the chosen farm, tailored configurations come into play. These configurations encompass diverse aspects such as caching mechanisms to expedite content delivery and filtering procedures to ensure content security. The Dispatcher meticulously adheres to these configurations to effectively manage the request.

Code Flow:

Here’s a breakdown of how the Dispatcher’s code flows:

• Starting Execution: The process starts in the “conf/httpd.conf” file, which leads to loading “conf.d/dispatcher_vhost.conf” as the next step.
• Loading Dispatcher Settings: Inside “dispatcher_vhost.conf,” we load two important files: “dispatcher.any” and “enabled_vhost.conf.”
• Configuring Dispatcher: The “dispatcher.any” file contains definitions for various things like farms. As we move along, this file helps configure client headers, virtual hosts, rendering settings, filters, vanity URLs, syndication post propagation, and caching.
• Enabling Virtual Hosts: The “enabled_vhost.conf” file helps us declare details like ports, hostnames, log file positions, whitelist rules, and rewrite rules.

This orchestration by the AEM Dispatcher embodies a systematic and methodical approach, navigating the intricacies of request routing while adhering to well-defined configurations and rules.

For more information, refer to:

• Resolving virtual host
• Defining farms

Configuration Files: Navigating Immutable and Mutable Settings

Crafting a thoughtfully organized configuration strategy empowers enterprises to achieve a harmonious equilibrium among system stability, security, and personalized enhancements.

In AEM Dispatcher, there are two types of configuration files: mutable and immutable.

Immutable Config Files:

• These files are like the foundation of a secure and working system set up by AMS (Adobe Managed Services).
• They’re locked to prevent accidental changes that might affect the system’s stability and security.
• You can’t directly modify these files, but you can create your own versions that build upon them.
• When AMS updates Dispatcher for fixes and security, your files won’t be altered, ensuring your changes remain intact.

Mutable Config Files:

• These are the files that can be changed and customized to suit your specific needs.
• You can alter their behavior and make adjustments without affecting the core system setup.
• Your customizations are isolated in separate areas, making them safe from conflicting with the system’s baseline.
• When AMS patches configurations, your customizations remain unaffected.
• The details on how we should configure the mutable files can be found on link

To explore the typical file structure of Dispatcher in both AMS and cloud environments, please refer to the following links:

• AMS hosted
• Cloud

Understanding AEM Dispatcher Modes

AEM Dispatcher offers two distinct operational modes:

• Flexible Mode
• Legacy Mode.

Activate Flexible Mode: To use Flexible Mode, you need to activate it by adding the folder and file opt-in/USE_SOURCES_DIRECTLY in your AEM Dispatcher configuration.

Variables in AEM dispatcher

In the world of AEM, making your website run smoothly involves smart configuration. Think of variables as your toolkit for making those configurations flexible and adaptable. These little helpers let you change things easily, like adjusting settings for different places your website might run or turning special features on and off. This article is your guide to understanding how variables can make your website work better, from smoothly moving between different setups to controlling how cool things show up on your site.

Few use cases for variables are:

1. Environment-Specific Configurations:
   Variables allow you to decouple environment-specific settings from configurations. By using variables to store environment-related values, you ensure that configuration files remain consistent across development, testing, and production environments, ensuring the same functional output in different scenarios.
2. Feature Toggling and Control: Variables can act as switches to enable or disable specific features or functionalities in your application.
3. Immutable File Handling: In cases where certain files are immutable (cannot be changed), variables provide a workaround. You can use variables to dynamically modify settings like log levels, allowing you to adjust the behavior of these otherwise unchangeable files without violating their immutability.
4. Conditional Include Statements: By leveraging variables like RUNMODE and ENV_TYPE, you can conditionally include specific configuration files based on the runtime mode or environment type. This enables seamless adaptation of configurations to different contexts without duplicating or modifying configuration files.
5. Domain and Hostname Matching: Variables can help you synchronize domain names and hostnames across different configurations.
6. Caching and TTL Management: Variables can be used to dynamically control cache settings such as cache timeouts (TTL). This is useful when you need to adjust caching behavior based on specific requirements or time-sensitive content updates.
7. Content Paths and Rewriting Rules: Variables can simplify the management of content paths and rewriting rules. You can create reusable rules that utilize variables for dynamic path generation, enhancing flexibility and making the configuration more maintainable.

Types of Variables in AEM Dispatcher

Variables in AEM Dispatcher allow you to adjust configuration settings dynamically. Here are the various types of variables and how to use them:

1. Baseline Variables: Baseline variables are predefined in the file conf.d/variables/global.vars. These default variables, like DISP_LOG_LEVEL, REWRITE_LOG_LEVEL, etc., ensure non-null values. Edit conf.d/variables/global.vars to modify values

   Define DISP_LOG_LEVEL info
   Define REWRITE_LOG_LEVEL debug

2. Custom Variables Files (.vars):
   Create .vars files in conf.d/variables/ to define your custom variables. These files hold variables specific to your code and can have any custom values. Example (techrevel.vars):

   Define WERETAIL_DOMAIN dev.weretail.com
   Define WERETAIL_ALT_DOMAIN dev.weretail.net

The custom .vars file can be incorporated through .vhost files. For instance, you can use a techrevel.vars file with a techrevel.vhost.

# Include customer defined variables
Include conf.d/variables/techrevel.vars

3. Environment Variables in AEMaaCS: In AEM as a Cloud Service (AEMaaCS), you have the ability to define environment variables using the Adobe I/O CLI or Cloud Manager. These variables can then be accessed in Dispatcher using the ${var} syntax, making it seamless to implement environment-specific configurations.
4. Environment Variables in AMS: Adobe Managed Services (AMS) introduces specific server and topology variables into the Apache process’ start-up arguments, encapsulated within the /etc/sysconfig/httpd file. This file acts as a storehouse for pre-defined variables tailored to your environment. Some of these variables are:

• AUTHOR_IP=”10.43.0.59″
• AUTHOR_PORT=”4502″
• AUTHOR_DOCROOT=’/mnt/var/www/author’
• PUBLISH_IP=”10.43.0.20″
• PUBLISH_PORT=”4503″
• PUBLISH_DOCROOT=’/mnt/var/www/html’
• ENV_TYPE=’dev’
• RUNMODE=’sites’

These variables are immutable and provided by AMS for server and topology differentiation, but they serve as powerful tools for configuring your setup.

Leveraging Global Environment Variables:

To effectively harness these environment variables across your configuration files, a strategic approach is employed. Due to the nature of how Apache services are initialized, a restart, rather than a reload, is necessary to incorporate changes. To globally include environment-based variables, the file /etc/httpd/conf.d/000_load_env_vars.conf is created.

This global configuration file leverages the variables set in /etc/sysconfig/httpd using the following structure:

IncludeOptional /etc/httpd/conf.d/variables/*_${ENV_TYPE}.vars
IncludeOptional /etc/httpd/conf.d/variables/*_${RUNMODE}.vars

As Apache starts, it pulls the variables set in /etc/sysconfig/httpd. By creating this global .conf file early in the loading process (with 000 ensuring its priority), the order of inclusion is assured.

Dynamic Inclusion Using Variables:

The utilization of variables in file naming further enhances the adaptability of this approach. Depending on the ENV_TYPE and RUNMODE values, a corresponding variables file is included:

• If ENV_TYPE is “dev,” the file loaded is /etc/httpd/conf.d/variables/weretail_domains_dev.vars.
• If ENV_TYPE is “stage,” the file loaded is /etc/httpd/conf.d/variables/weretail_domains_stage.vars.
• Similarly, for different RUNMODE values, corresponding variable files are included.

These included files enable the utilization of stored variable names.

Variable-Powered Configuration:

In the weretail.vhost file located in /etc/httpd/conf.d/available_vhosts/, the traditional syntax is transformed using the power of variables:

From:

<VirtualHost *:80>
 ServerName dev.weretail.com
 ServerAlias dev.weretail.net

To:

<VirtualHost *:80>
 ServerName ${WERETAIL_DOMAIN}
 ServerAlias ${WERETAIL_ALT_DOMAIN}

By adopting this dynamic approach, you can seamlessly adapt your configuration across different environments and modes, ensuring consistency and efficiency in your AEM Dispatcher setup.

Implementing Environment Variables with Local Docker Dispatcher

In AEM as a Cloud Service (AEMaaCS), harnessing environment variables through the Adobe I/O CLI empowers you to fine-tune configurations using the ${var} syntax within Dispatcher. But what about achieving this same capability with the local Dispatcher SDK?

To seamlessly set up environment variables locally, you can leverage the ENV_FILE parameter in the following way:

• Begin by crafting a dedicated “.txt” or “.env” file containing your desired environment variables. Declare variables

ENV_VAR=testENV.com

• Now, assign the path of your environment variables file to ENV_FILE. For instance, execute the command:

SET ENV_FILE=env/variables.txt

• Commence your AEM Dispatcher by initiating the command:

bin\docker_run src 192.168.0.118:4503 8080

How to validate if the variable is available in docker?

Once the docker starts, open its terminal.

execute echo ${ENV_FILE}. If it doesn’t return value, set the ENV_FILE attribute in system-level environment variable. Restart Dispatcher

• Voilà! Your environment variables are now in play, seamlessly enhancing your local AEM Dispatcher setup.

Other available parameters are:

Environment Variables Available:

By employing these steps, you extend the power of environment variables locally, mirroring the dynamic capabilities of AEM as a Cloud Service, and thus enhancing the adaptability and control of your Dispatcher configurations.