Expose common web.xml configuration settings as environment variables

[yolabingo]

Description

Claude helped me here, please review for bad assumptions before proceeding.

dotCMS exposes common Tomcat configuration settings as environment variables (CMS_* prefix) for conf/server.xml and conf/context.xml, allowing operators to tune runtime behavior without rebuilding the image. conf/web.xml and WEB-INF/web.xml have no equivalent support — settings like session timeout and security header parameters are hardcoded.

File inventory

File	Container path	Source	Native ${ENV_VAR} support
conf/web.xml	/srv/dotserver/tomcat-*/conf/web.xml	Apache Tomcat distribution (no custom override in repo)	✅ Yes — same mechanism as server.xml
WEB-INF/web.xml	/srv/dotserver/tomcat-*/webapps/ROOT/WEB-INF/web.xml	dotCMS/src/main/webapp/WEB-INF/web.xml	❌ No — Servlet spec does not define variable interpolation

---

conf/web.xml — implementation path (straightforward)

Tomcat's global conf/web.xml uses the same IntrospectionUtils variable substitution as server.xml and context.xml. The repo already has an override mechanism:

1. Files in dotCMS/src/main/resources/container/tomcat9/conf/ replace Tomcat distribution defaults at build time.
2. Each file is registered as a <configfile> in the Cargo Maven plugin section of dotCMS/pom.xml.

Adding conf/web.xml requires:

• Creating dotCMS/src/main/resources/container/tomcat9/conf/web.xml (based on Tomcat 9.x default)
• Replacing selected hardcoded values with ${CMS_*:-default} syntax
• Adding a <configfile> entry in dotCMS/pom.xml after the existing context.xml entry (~line 2153)

---

WEB-INF/web.xml — constraint and options

The Servlet specification does not define variable interpolation for WEB-INF/web.xml. Tomcat's IntrospectionUtils resolver is not invoked for this file — ${MY_VAR} is treated as a literal string.

Initially targeted settings (in scope for this issue):

<filter>
    <filter-name>HttpHeaderSecurityFilter</filter-name>
    <filter-class>org.apache.catalina.filters.HttpHeaderSecurityFilter</filter-class>
    <async-supported>true</async-supported>
    <init-param>
        <param-name>hstsMaxAgeSeconds</param-name>
        <param-value>3600</param-value>
    </init-param>
    <init-param>
        <param-name>hstsIncludeSubDomains</param-name>
        <param-value>true</param-value>
    </init-param>
    <init-param>
        <param-name>antiClickJackingOption</param-name>
        <param-value>SAMEORIGIN</param-value>
    </init-param>
</filter>

<session-config>
    <session-timeout>30</session-timeout>
</session-config>

Setting	Suggested env var	Current value
hstsMaxAgeSeconds	${CMS_HSTS_MAX_AGE_SECONDS:-3600}	3600
hstsIncludeSubDomains	${CMS_HSTS_INCLUDE_SUBDOMAINS:-true}	true
antiClickJackingOption	${CMS_ANTI_CLICK_JACKING_OPTION:-SAMEORIGIN}	SAMEORIGIN
session-timeout	${CMS_SESSION_TIMEOUT:-30}	30

Workaround options for WEB-INF/web.xml (developer decision required):

Option	Approach	Notes
A	Startup script (envsubst) rewrites WEB-INF/web.xml at container startup	No code changes; requires file writable at runtime
B	Subclass org.apache.catalina.filters.HttpHeaderSecurityFilter, override init() to check env vars	Clean; requires maintenance per Tomcat upgrade
C	Move session-timeout to conf/web.xml (native support); handle filter settings separately	Practical quick win for session timeout

---

References

• Existing overrides: dotCMS/src/main/resources/container/tomcat9/conf/
• Cargo configfiles section: dotCMS/pom.xml ~lines 2148–2155
• Dockerfile: dotCMS/src/main/docker/original/Dockerfile
• App web.xml: dotCMS/src/main/webapp/WEB-INF/web.xml
• Add additional docker env variables for commonly changed settings #26757 (review) -- previous swing at this

---

Acceptance Criteria

WEB-INF/web.xml — initial settings

• hstsMaxAgeSeconds configurable via CMS_HSTS_MAX_AGE_SECONDS (default: 3600)
• hstsIncludeSubDomains configurable via CMS_HSTS_INCLUDE_SUBDOMAINS (default: true)
• antiClickJackingOption configurable via CMS_ANTI_CLICK_JACKING_OPTION (default: SAMEORIGIN)
• session-timeout configurable via CMS_SESSION_TIMEOUT (default: 30)
• Chosen workaround approach documented and justified

conf/web.xml (optional stretch goal)

• dotCMS/src/main/resources/container/tomcat9/conf/web.xml created, based on Tomcat 9.x default
• File registered in dotCMS/pom.xml Cargo configfiles alongside server.xml and context.xml

Both

• Env var names follow existing CMS_ prefix convention
• Container starts with default configuration (no env vars set)
• Container starts with non-default values for all new env vars
• No regression in existing CMS_* env var behavior