Migrate from wcm.io CONGA AEM Definitions 0.x to 1.x

1 Problem
2 Solution
3 Related articles

Problem

You have an existing AEM Projects that uses wcm.io DevOps CONGA and CONGA AEM Definitions 0.x for automating your AEM infrastructure deployments. You want to update to AEM Definitions 1.x.

Solution

With WDCONGA-14, WDCONGA-12 and WDCONGA-18 the roles for AEM Dispatcher where refactored and are now much more powerful than before. But there are some backward-incompatible changes, you need to update your environment for the aspects listed in this page.

Remove role aem-disptacher-common

Remove all references to the role aem-dispatcher-common - it is now part of the new role aem-dispatcher.

Replace role aem-dispatcher-author

Replace all references to the role aem-dispatcher-author with the role aem-dispatcher.
Add a new variant aem-author.
Remove references to variants no-ssland no-ssl+ssl, use only the variant ssl if HTTPS should be supported. That means that HTTP support is always activated implicitly - but you can set httpd.ssl.enforce to enforce a redirect to SSL.

Example:

Old definition	New definition

Old definition	New definition
`- role: aem-dispatcher-author variant: ssl`	`- role: aem-dispatcher variants: - aem-author - ssl`

Replace role aem-dispatcher-publish

Replace all references to the role aem-dispatcher-publish with the role aem-dispatcher.
Add a new variant aem-publish.
Remove references to variants no-ssland no-ssl+ssl, use only the variant ssl if HTTPS should be supported. That means that HTTP support is always activated implicitly.

Example:

Old definition	New definition

Old definition	New definition
`- role: aem-dispatcher-publish variant: no-ssl+ssl`	`- role: aem-dispatcher variants: - aem-publish - ssl`

Changed configuration property names of aem-dispatcher-* roles

Check your environments (or custom templates) if you reference any of these property names and change them according to this table:

Old property name	New property name

Old property name	New property name
`cmsAuthorHostname`	`httpd.serverName`
`cmsAuthorHostnameSsl`	`httpd.serverNameSsl`
`serverAliasNames`	`httpd.serverAliasNames`
`serverNameSsl`	`httpd.serverNameSsl`
`dispatcher.allowAdminAccessFromHost`	`httpd.accessRestriction.adminAccessFromHost`
`dispatcher.allowAdminAccessFrom`	`httpd.accessRestriction.adminAccessFromIp`
`dispatcher.allowFlushFromHost`	`httpd.accessRestriction.dispatcherFlushFromHost`
`dispatcher.allowFlushFrom`	`httpd.accessRestriction.dispatcherFlushFromIp`
`dispatcher.rootRedirectUrl`	`httpd.rootRedirect.url`
`dispatcher.rootRedirectHttpStatus`	`httpd.rootRedirect.httpStatus`
`dispatcher.corsHeader.*`	`httpd.corsHeader.*`
`dispatcher.sslCertificateFile`	`httpd.ssl.certificateFile`
`dispatcher.sslCertificateKeyFile`	`httpd.ssl.certificateKeyFile`
`dispatcher.sslCACertificatePath`	`httpd.ssl.caCertificatePath`
`dispatcher.sslCACertificateFile`	`httpd.ssl.caCertificateFile`
`dispatcher.enforceSsl`	`httpd.ssl.enforce`
`dispatcher.tenantSpecificVHostConfig`	`httpd.customVHostConfig.beforeRewrite`
`slingMappingPath`	`sling.mapping.rootPath`
`slingMappingAllowUnshortenedPath`	`sling.mapping.allowUnshortenedPath`
`dispatcher.cacheRootPath`	`dispatcher.cache.rootPath`
`dispatcher.statFilesLevel`	`dispatcher.cache.statFilesLevel`
`dispatcher.cacheDamAssets`	No replacement - but you can add caching rules on your own
`dispatcher.moduleFile`	No replacement - should be handled outside CONGA (e.g. in Ansible Role)

Changes in Handlebars templates of aem-dispatcher-* roles

The shared config file _vhost_publish_shared_include.conf.hbs was removed and integrated into vhost_publish_tenant.partials.hbs - this allows to override only parts of it using partials, and it allows different configuration for different tenants.
vhost_author.partials.hbs: Partial accessRestrictions was split up in multiple blocks
The template dispatcher.load.hbs was removed

Changes in file layout for the aem-dispatcher role

The files generated by the aem-dispatcher role are now created in a "distro-agnostic" folder structure:

+-- vhosts.d/
    |-- vhost_*.conf
+-- conf.d/
    |-- dispatcher.conf
+-- dispatcher.d/
    |-- dispatcher_*.any