Doc: Add Guide for Configuring HotSwap Agent with Java 17

[korutx]

Description

This PR adds comprehensive documentation to configure HotSwap Agent for Java 17 in the Alfresco SDK 4 context. The guide outlines the steps required to modify the default Alfresco Content Services (ACS) Docker image to support HotSwapAgent with Java 17, using a pre-built JetBrains Runtime OpenJDK.

Key Changes:

Documentation update

• Updated the hotswap-agent.md file with new instructions on configuring HotSwapAgent for Java 17.
• Included steps to download and configure the JetBrains Runtime OpenJDK and HotSwapAgent.
• Provided detailed Dockerfile modifications to install and configure the custom JDK for HotSwapAgent.
• Added necessary updates to the docker-compose.yml

[jirikx]

Shouldn't this contain the ${TOMCAT_DIR}/conf/catalina.properties like this?:

RUN sed -i '/^shared.loader=/ s|$|,${catalina.base}/hotswap-agent/sample-project-platform/target/classes|' \
    ${TOMCAT_DIR}/conf/catalina.properties

[jirikx]

Can you also share the Alfresco SDK version which you have used to test this procedure, please? I'm unable to make the HotSwap Agent work on the Alfresco SDK 4.10 due to the following error:

myapp-acs-1       | 17-Feb-2025 15:38:50.939 INFO [main] org.apache.catalina.startup.HostConfig.deployDirectory Deploying web application directory [/usr/local/tomcat/webapps/ROOT]
myapp-acs-1       | 17-Feb-2025 15:38:50.941 SEVERE [main] org.apache.catalina.startup.HostConfig.deployDirectory The web application with context path [] was not deployed because it contained a deployment descriptor [/usr/local/tomcat/webapps/ROOT/META-INF/context.xml] which may include configuration necessary for the secure deployment of the application but processing of deployment descriptors is prevented by the deployXML setting of this host. An appropriate descriptor should be created at [/usr/local/tomcat/conf/Catalina/localhost/ROOT.xml] to deploy this application.
myapp-acs-1       | 17-Feb-2025 15:38:50.950 SEVERE [main] org.apache.catalina.startup.HostConfig.deployDirectory Error deploying web application directory [/usr/local/tomcat/webapps/ROOT]
myapp-acs-1       |  java.lang.IllegalStateException: Error starting child
myapp-acs-1       |          at org.apache.catalina.core.ContainerBase.addChildInternal(ContainerBase.java:602)
myapp-acs-1       |          at org.apache.catalina.core.ContainerBase.addChild(ContainerBase.java:571)
myapp-acs-1       |          at org.apache.catalina.core.StandardHost.addChild(StandardHost.java:654)
myapp-acs-1       |          at org.apache.catalina.startup.HostConfig.deployDirectory(HostConfig.java:1130)
myapp-acs-1       |          at org.apache.catalina.startup.HostConfig$DeployDirectory.run(HostConfig.java:1933)
myapp-acs-1       |          at java.base/java.util.concurrent.Executors$RunnableAdapter.call(Executors.java:539)
myapp-acs-1       |          at java.base/java.util.concurrent.FutureTask.run(FutureTask.java:264)
myapp-acs-1       |          at org.apache.tomcat.util.threads.InlineExecutorService.execute(InlineExecutorService.java:75)
myapp-acs-1       |          at java.base/java.util.concurrent.AbstractExecutorService.submit(AbstractExecutorService.java:123)
myapp-acs-1       |          at org.apache.catalina.startup.HostConfig.deployDirectories(HostConfig.java:1041)
myapp-acs-1       |          at org.apache.catalina.startup.HostConfig.deployApps(HostConfig.java:425)
myapp-acs-1       |          at org.apache.catalina.startup.HostConfig.start(HostConfig.java:1629)
myapp-acs-1       |          at org.apache.catalina.startup.HostConfig.lifecycleEvent(HostConfig.java:303)
myapp-acs-1       |          at org.apache.catalina.util.LifecycleBase.fireLifecycleEvent(LifecycleBase.java:109)
myapp-acs-1       |          at org.apache.catalina.util.LifecycleBase.setStateInternal(LifecycleBase.java:385)
myapp-acs-1       |          at org.apache.catalina.util.LifecycleBase.setState(LifecycleBase.java:332)
myapp-acs-1       |          at org.apache.catalina.core.ContainerBase.startInternal(ContainerBase.java:776)
myapp-acs-1       |          at org.apache.catalina.core.StandardHost.startInternal(StandardHost.java:772)
myapp-acs-1       |          at org.apache.catalina.util.LifecycleBase.start(LifecycleBase.java:164)
myapp-acs-1       |          at org.apache.catalina.core.ContainerBase$StartChild.call(ContainerBase.java:1203)
myapp-acs-1       |          at org.apache.catalina.core.ContainerBase$StartChild.call(ContainerBase.java:1193)
myapp-acs-1       |          at java.base/java.util.concurrent.FutureTask.run(FutureTask.java:264)
myapp-acs-1       |          at org.apache.tomcat.util.threads.InlineExecutorService.execute(InlineExecutorService.java:75)
myapp-acs-1       |          at java.base/java.util.concurrent.AbstractExecutorService.submit(AbstractExecutorService.java:145)
myapp-acs-1       |          at org.apache.catalina.core.ContainerBase.startInternal(ContainerBase.java:749)
myapp-acs-1       |          at org.apache.catalina.core.StandardEngine.startInternal(StandardEngine.java:203)
myapp-acs-1       |          at org.apache.catalina.util.LifecycleBase.start(LifecycleBase.java:164)
myapp-acs-1       |          at org.apache.catalina.core.StandardService.startInternal(StandardService.java:415)
myapp-acs-1       |          at org.apache.catalina.util.LifecycleBase.start(LifecycleBase.java:164)
myapp-acs-1       |          at org.apache.catalina.core.StandardServer.startInternal(StandardServer.java:874)
myapp-acs-1       |          at org.apache.catalina.util.LifecycleBase.start(LifecycleBase.java:164)
myapp-acs-1       |          at org.apache.catalina.startup.Catalina.start(Catalina.java:757)
myapp-acs-1       |          at java.base/jdk.internal.reflect.NativeMethodAccessorImpl.invoke0(Native Method)
myapp-acs-1       |          at java.base/jdk.internal.reflect.NativeMethodAccessorImpl.invoke(NativeMethodAccessorImpl.java:77)
myapp-acs-1       |          at java.base/jdk.internal.reflect.DelegatingMethodAccessorImpl.invoke(DelegatingMethodAccessorImpl.java:43)
myapp-acs-1       |          at java.base/java.lang.reflect.Method.invoke(Method.java:568)
myapp-acs-1       |          at org.apache.catalina.startup.Bootstrap.start(Bootstrap.java:345)
myapp-acs-1       |          at org.apache.catalina.startup.Bootstrap.main(Bootstrap.java:473)
myapp-acs-1       |  Caused by: org.apache.catalina.LifecycleException: Failed to process either the global, per-host or context-specific context.xml file therefore the [] Context cannot be started.
myapp-acs-1       |          at org.apache.catalina.startup.FailedContext.startInternal(FailedContext.java:229)
myapp-acs-1       |          at org.apache.catalina.util.LifecycleBase.start(LifecycleBase.java:164)
myapp-acs-1       |          at org.apache.catalina.core.ContainerBase.addChildInternal(ContainerBase.java:599)
myapp-acs-1       |          ... 37 more
myapp-acs-1       | 17-Feb-2025 15:38:50.952 INFO [main] org.apache.catalina.startup.HostConfig.deployDirectory Deployment of web application directory [/usr/local/tomcat/webapps/ROOT] has finished in [12] ms

I think that this is caused by the line command: ["catalina.sh", "run"] from docker/docker-compose.yml, but its removal causes different problems, so I'm kind of lost.

Before that, I had to change the line from step 9, since the ACS wouldn't start due to the missing path to catalina.properties, but didn't modify anything else.

RUN sed -i '/^shared.loader=/ s|$|,${catalina.base}/hotswap-agent/sample-project-platform/target/classes|' \
    ${TOMCAT_DIR}/conf/catalina.properties

[jirikx]

jbr_jcef-17.0.11-linux-x64-b1207.30 doesn't contain the bin/jar file, but the developer binary jbrsdk_jcef-17.0.11-linux-x64-b1207.30.tar.gz does. Shouldn't we use that binary instead? Also, is the version with JCEF necessary? I think that the plain JBRSDK would suffice, since it already contains DCEVM.