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

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 definitionNew 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 definitionNew 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 nameNew property name
cmsAuthorHostnamehttpd.serverName
cmsAuthorHostnameSsl httpd.serverNameSsl
serverAliasNameshttpd.serverAliasNames
serverNameSslhttpd.serverNameSsl
dispatcher.allowAdminAccessFromHosthttpd.accessRestriction.adminAccessFromHost
dispatcher.allowAdminAccessFromhttpd.accessRestriction.adminAccessFromIp
dispatcher.allowFlushFromHosthttpd.accessRestriction.dispatcherFlushFromHost
dispatcher.allowFlushFromhttpd.accessRestriction.dispatcherFlushFromIp
dispatcher.rootRedirectUrlhttpd.rootRedirect.url
dispatcher.rootRedirectHttpStatushttpd.rootRedirect.httpStatus
dispatcher.corsHeader.*httpd.corsHeader.*
dispatcher.sslCertificateFilehttpd.ssl.certificateFile
dispatcher.sslCertificateKeyFilehttpd.ssl.certificateKeyFile
dispatcher.sslCACertificatePathhttpd.ssl.caCertificatePath
dispatcher.sslCACertificateFilehttpd.ssl.caCertificateFile
dispatcher.enforceSslhttpd.ssl.enforce
dispatcher.tenantSpecificVHostConfighttpd.customVHostConfig.beforeRewrite
slingMappingPathsling.mapping.rootPath
slingMappingAllowUnshortenedPathsling.mapping.allowUnshortenedPath
dispatcher.cacheRootPathdispatcher.cache.rootPath
dispatcher.statFilesLeveldispatcher.cache.statFilesLevel
dispatcher.cacheDamAssetsNo replacement - but you can add caching rules on your own
dispatcher.moduleFileNo 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