@adobe/aem-cs-source-migration-dispatcher-converter

@adobe/aem-cs-source-migration-dispatcher-converter

aem-cs-source-migration-dispatcher-converter provides the capability for configuring existing on-premise or Adobe Managed Services Dispatcher configurations to AEM as a Cloud Service compatible Dispatcher configuration.

Introduction

The goal of this project is to make it as simple as possible for AEM developers to migrate existing AEM Dispatcher configurations to AEM as a Cloud Service compatible dispatcher configurations.

Usage

While it is recommended to use this tool via our AIO CLI plugin for source migration (refer to aio-cli-plugin-aem-cloud-service-migration), it can also be executed standalone.

Installation

This project uses node and npm. Go check them out if you don't have them locally installed.

It can be installed like any other Node.js module.

$ npm install @adobe/aem-cs-source-migration-dispatcher-converter

Adding the Module Requirement

To add the module to your Node.js project:

• Install the module in your project.
• Add the require function in the module in the javascript file where it will be consumed:

const DispatcherConverter = require('@adobe/aem-cs-source-migration-dispatcher-converter');

How it works

1. Copy the configuration to Target Folder

• The dispatcher configuration path provided in the config.yaml is used to copy the configuration to the target folder.
• The copied dispatcher configurations are processed by the tool and converted dispatcher configurations are placed under target folder.

2. Remove non-conforming segments

In this part below non-conforming segments are removed:

• Unused Folders are removed
• Non Publish Vhost Files are removed
• Vhost sections not referring to Port 80 are removed
• Variables used in configuration can also be renamed as per the requirement. For On Premise configurations, additional variables can be defined in variablesToReplace section in config file to be replaced.

3. Convert configuration segment related to httd.conf

In this phase the tool changes the configuration dependent on httpd.conf which includes below operations:

• Change virtualhost files.
  • You can have one or more of these files.
  • They contain <VirtualHost> entries that match host names and allow Apache to handle each domain traffic with different rules.
  • Files are created in the available_vhosts directory and enabled with a symbolic link in the enabled_vhosts directory.
• Create symlinks for virtualhost files in enabled vhost section.
• Checking for non-whitelisted directives in the configuration.

4. Convert configuration segment related to dispatcher.any

In this phase the tool changes the configuration dependent on dispatcher.any which includes below operations:

• Creating/Changing farm files.
  • You can have one or more of these files, and they contain farms to match host names and allow the dispatcher module to handle each farm with different rules.
  • Files are created in the available_farms directory and enabled with a symbolic link in the enabled_farms directory.
• Creating symlinks for farm files under enabled farms section.
• Creating render files
  • Part of base framework, this file gets generated on startup. You are required to include this file in every farm you define, in the renders section.
• Creating rules files
  • This file is included from inside your .farm files. It specifies caching preferences.
• Creating filter files
  • This file is included from inside your .farm files. It has a set of rules that change what traffic should be filtered out and not make it to the backend.
• Creating clientheaders files
  • This file is included from inside your .farm files. It specifies what request headers should be forwarded to the backend.
• Creating rewrite files.
  • This file is included from inside your .vhost files. It has a set of rewrite rules for mod_rewrite.

5. Summary report

• Every operation which is performed during the conversion it is tracked and written to dispatcher-converter-report.md.

How to execute

To execute the repository-modernizer tool locally :

• Run git clone [e-mail]:adobe/aem-cloud-service-source-migration.git to clone the repository locally
• Navigate to the dispatcher-converter folder
• Run npm install to install all the required dependencies
• Inside the executors folder:
  • add the required configurations to config.yaml. Refer to Configurations sections below to know more.
  • run node main.js to execute the tool on customer's Adobe Managed Services (AMS) dispatcher configurations
  • run node singleFileMain.js to execute the tool on customer's on-Premise dispatcher configurations
  • target/dispatcher/src/ will contain the resulting restructured projects

Configurations

The dispatcher converter configuration uses YAML to define necessary configurations. Due to the known nature of Adobe Managed Services (AMS) dispatcher configurations, the configurations required for converting them to be AEM as a Cloud Service compatible dispatcher configurations, are relatively simple. However, since there are fewer restrictions to on-premise implementations, more specific configurations are necessary.

As sample configuration is below:

Property	Description
sdkSrc*	Path to your dispatcher sdk source code. You must include the src folder itself in the path.
onPremise/dispatcherAnySrc	Path to the dispatcher.any file.
onPremise/httpdSrc	Path to the httpd.conf file (the main apache config file) - If vhostsToConvert is not specified you can use this property to find vhosts by parsing the main apache file.
onPremise/vhostsToConvert	Array of paths to vhosts files and/or vhost folders containing vhost files you wish to convert to cloud service configurations.
onPremise/variablesToReplace	Array of mapped objects that replace existing variables with new variables. The original variable is first and the variable to replace is second.
onPremise/appendToVhosts	This can be a file that you want to append to every vhost file in case you need logic added to all configurations. This is useful to replace logic that was once stored in your main apache config file.
onPremise/pathToPrepend	Array of paths to existing dispatcher configuration root folders to scan for the included files. These paths help to map includes in the configurations to their current location in the provided folder structure.
In case the files are distributed across all the folders use command for i in $(find pwd -type d); do echo "- \"$i/\""; done for unix based system and dir /s /b /o:n /ad for windows to generate folder/sub-folder and paste the output here.
onPremise/portsToMap	Only port 80 is supported in AEM as a Cloud Service - if you were using a non standard port here and need it mapped in AEM, provide it here - all other vhosts with non default ports will be removed.
ams/cfg*	Path to dispatcher configuration folder (expected immediate subfolders - conf, conf.d, conf.dispatcher.d and conf.modules.d)
* denotes required field

dispatcherConverter:
    # Path to the src folder of the dispatcher sdk. You must include the src folder itself in the path.
    sdkSrc: "/Users/{username}/some/path/to/dispatcher-sdk-2.0.21/src"
    # Add information about on-premise dispatcher configuration here
	onPremise:
        # Path to the dispatcher.any file
        dispatcherAnySrc: "/Users/{username}/some/path/to/dispatcher.any"
        # Path to the httpd.conf file (the main apache config file)
        # If `vhostsToConvert` is not specified you can use this property to find vhosts by parsing the main apache file
        httpdSrc: "/Users/{username}/some/path/to/httpd.conf"
        # Array of paths to vhosts files and/or vhost folders containing vhost files you wish to convert to cloud service configurations
        vhostsToConvert:
            - "/Users/{username}/some/path/to/mywebsite.vhost"
            - "/Users/{username}/some/path/to/myotherwebsite.vhost"
            - "/Users/{username}/some/path/to/vhostfolder"
        # Array of mapped objects that replace existing variables with new variables.
        # The original variable is first and the variable to replace is second
        variablesToReplace:
            TIER: "ENVIRONMENT_TYPE"
        # This can be a file that you want to append to every vhost file in case you need logic added to all configurations.
        # This is useful to replace logic that was once stored in your main apache config file.
        appendToVhosts:
            - "/Users/{username}/some/path/to/appendedContent.conf"
        # Array of paths to existing dispatcher configuration root folders to scan for the included files.
        # These paths help to map includes in the configurations to their current location in the provided folder structure.
        # In case the files are distributed across all the folders use command `for i in $(find `pwd` -type d); do echo "- \"$i/\""; done` for unix based system
        # and `dir /s /b /o:n /ad` for windows to generate folder/sub-folder and paste the output here.
        pathToPrepend:
            - "/Users/{username}/some/path/to/your/httpd/content/"
        # Only port 80 is supported in AEM as a Cloud Service - if you were using a non standard port here and need it mapped
        # in AEM, provide it here - all other vhosts with non default ports will be removed.
        portsToMap:
            - 8000
            - 8080
    # Add information about Adobe Managed Services dispatcher configuration here
    ams:
        # Path to dispatcher configuration folder
        # (expected immediate subfolders - conf, conf.d, conf.dispatcher.d and conf.modules.d)
        cfg: "/Users/{username}/some/path/to/dispatcher/folder"

Validating the output

[NOTE] For more information on Dispatcher Validator, refer to Adobe Experience Manager as a Cloud Service SDK.

• Run the dispatcher validator on the converted configurations, with the dispatcher sub-command:

  $ validator dispatcher
  

• If you encounter errors about missing include files, check whether you correctly renamed those files.

• If you see errors concerning undefined variable PUBLISH_DOCROOT, rename it to DOCROOT.

For troubleshooting other errors, refer to Troubleshooting & Local Validation of Dispatcher Configuration.

Known Limitations

• Rule file which exists in original configuration and having name non-conforming to Skyline Guidelines can be removed.
• If removed file is required, it should be converted manually and used.

Contributing

Contributions are welcomed! Refer to Contributing Guide for more information.

Licensing

This project is licensed under the Apache V2 License. Refer to LICENSE for more information.