Expected usage of the various ways to specific Pega config params should be clearly documented

[pega-embate]

Currently, within the Pega docker image there are multiple ways to specify confg params.
prweb.xml
context.xml
CATALINA_OPTS
prconfig.xml (in helm charts)

It is not clear which mechanism should be used for different types of params.

A document describing the expected usage of each config file would clarify what should go where

[petejo]

Proposal:

prweb.xml - This file should contain any configuration that is required when running inside a docker container. Ideally, this is a very small file for legacy settings, as the OOTB default behavior for new settings should generally assume Pega is running in containers. This file should not be modifiable at container startup.

context.xml - This file can be injected (e.g. via a Helm generated configMap) by the orchestration via mounting (see entrypoint.sh), otherwise a default dockerize template is leveraged to create the file. As a best practice, it should only contain Apache Tomcat specific configuration, and decouple the Pega configuration, allowing the image to more easily adopt any potential Apache Tomcat format changes as we move to their later versions.

prconfig.xml - This file can also be injected by the orchestration, otherwise Pega's OOTB default inside the .war file is used. This allows for deployment tier level Pega configuration.

CATALINA_OPTS - This should only ever be used by a basic Docker run command or custom orchestration which cannot inject files (e.g. not K8S)

In summary, if the setting is required by Pega in order to run successfully for all deployment tiers (e.g. all Pega node types) then prweb.xml is the desired location. K8S (or any sophisticated orchestration) users who need to customize per deployment tier or per environment should use prconfig.xml for Pega configuration, and finally, CATALINA_OPTS allows for individual Docker run or basic orchestration to configure the container.

[pega-embate]

Current version of https://github.com/pegasystems/pega-helm-charts/blame/master/charts/pega/README.md documents the config files. Current maintainers should assess validity and required enhancements to this content.

[kishorv10]

US-613495 (internal)