Deploying on Jetty 12 using context XML files will only work when a .properties file with the EE details is also present

[alitokmen]

Jetty version(s)
Jetty 12 (beta 3)

Java version/vendor (use: java -version)
openjdk version "17.0.7" 2023-04-18
OpenJDK Runtime Environment (build 17.0.7+7-Ubuntu-0ubuntu122.04.2)
OpenJDK 64-Bit Server VM (build 17.0.7+7-Ubuntu-0ubuntu122.04.2, mixed mode, sharing)

OS type/version
Distributor ID: Ubuntu
Description: Ubuntu 22.04.2 LTS
Release: 22.04
Codename: jammy

Description
When I follow the steps in https://eclipse.dev/jetty/documentation/jetty-12/operations-guide/index.html#og-deploy-jetty the presence of the Jetty context XML file has no impact - Nothing gets deployed at all.

The (almost) same context XML file has been working for many previous Jetty versions (actually, all the way to Jetty 6.x), I hence believe this is a regression.

How to reproduce?

1. Create a Jetty context XML file, similar to the below - I created a file webapps/simple-war.xml with contents:

<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE Configure PUBLIC "-//Jetty//Configure//EN" "https://www.eclipse.org/jetty/configure_10_0.dtd">

<Configure class="org.eclipse.jetty.ee10.webapp.WebAppContext">
  <Set name="contextPath">/simple-war</Set>
  <Set name="war">/home/hyper-v/cargo/core/samples/java/target/deployables-jakarta-ee/simple-war.war</Set>
</Configure>

2. Start the Jetty server, the logs show no deployment of the context XML file:

2023-07-26 20:38:01.258:INFO :oejs.Server:main: jetty-12.0.0.beta3; built: 2023-07-03T21:07:40.128Z; git: 3c948df481846fa922f841aa20857f18c92736e5; jvm 17.0.7+7-Ubuntu-0ubuntu122.04.2
2023-07-26 20:38:01.295:INFO :oejdp.ScanningAppProvider:main: Deployment monitor ee10 in [file:///home/hyper-v/cargo/core/samples/java/target/jetty-base/webapps/] at intervals 0s
2023-07-26 20:38:01.310:INFO :oejs.DefaultSessionIdManager:main: Session workerName=node0
2023-07-26 20:38:01.331:INFO :oejs.AbstractConnector:main: Started ServerConnector@36b4fd29{HTTP/1.1, (http/1.1)}{0.0.0.0:8080}
2023-07-26 20:38:01.339:INFO :oejs.Server:main: Started oejs.Server@ea6147e{STARTING}[12.0.0.beta3,sto=5000] @768ms

Other observations - The same with the WAR file copied over
Copying over the WAR file works:

1. Execute (in my case): cp /home/hyper-v/cargo/core/samples/java/target/deployables-jakarta-ee/simple-war.war webapps/
2. Start the Jetty server, now the logs show the WAR is getting deployed:

2023-07-26 20:36:37.218:INFO :oejs.Server:main: jetty-12.0.0.beta3; built: 2023-07-03T21:07:40.128Z; git: 3c948df481846fa922f841aa20857f18c92736e5; jvm 17.0.7+7-Ubuntu-0ubuntu122.04.2
2023-07-26 20:36:37.252:INFO :oejdp.ScanningAppProvider:main: Deployment monitor ee10 in [file:///home/hyper-v/cargo/core/samples/java/target/jetty-base/webapps/] at intervals 0s
2023-07-26 20:36:37.261:INFO :oejd.DeploymentManager:main: addApp: App@38cee291[ee10,null,/home/hyper-v/cargo/core/samples/java/target/jetty-base/webapps/simple-war.war]
2023-07-26 20:36:37.365:INFO :oejew.StandardDescriptorProcessor:main: NO JSP Support for /simple-war, did not find org.eclipse.jetty.ee10.jsp.JettyJspServlet
2023-07-26 20:36:37.378:INFO :oejsh.ContextHandler:main: Started oeje10w.WebAppContext@48b67364{Simple Webapp,/simple-war,b=file:///tmp/jetty-0_0_0_0-8080-simple-war_war-_simple-war-any-4096158269517142805/webapp/,a=AVAILABLE,h=oeje10s.SessionHandler@189cbd7c{STARTED}}{/home/hyper-v/cargo/core/samples/java/target/jetty-base/webapps/simple-war.war}
2023-07-26 20:36:37.387:INFO :oejes.ServletContextHandler:main: Started oeje10w.WebAppContext@48b67364{Simple Webapp,/simple-war,b=file:///tmp/jetty-0_0_0_0-8080-simple-war_war-_simple-war-any-4096158269517142805/webapp/,a=AVAILABLE,h=oeje10s.SessionHandler@189cbd7c{STARTED}}{/home/hyper-v/cargo/core/samples/java/target/jetty-base/webapps/simple-war.war}
2023-07-26 20:36:37.390:INFO :oejs.DefaultSessionIdManager:main: Session workerName=node0
2023-07-26 20:36:37.404:INFO :oejs.AbstractConnector:main: Started ServerConnector@ff55d30{HTTP/1.1, (http/1.1)}{0.0.0.0:8080}
2023-07-26 20:36:37.415:INFO :oejs.Server:main: Started oejs.Server@ea6147e{STARTING}[12.0.0.beta3,sto=5000] @957ms

[joakime]

You have a project wanting org.eclipse.jetty.ee10.webapp.WebAppContext
So that means you'll want the module ee10-deploy enabled, not core-deploy

[joakime]

An interesting wrinkle in this report is that the OP only has an XML deployable, no war or exploded directory in the webapps/ dir.
The XML has a reference to the war OUTSIDE of the webapps directory. (which should be a totally valid setup)

[alitokmen]

You have a project wanting org.eclipse.jetty.ee10.webapp.WebAppContext So that means you'll want the module ee10-deploy enabled, not core-deploy

Thanks for the note - I am happy to remove that part when it is confusing. Apologies.

[alitokmen]

An interesting wrinkle in this report is that the OP only has an XML deployable, no war or exploded directory in the webapps/ dir. The XML has a reference to the war OUTSIDE of the webapps directory. (which should be a totally valid setup)

Indeed, the (almost) same context XML file has been working for many previous Jetty versions (actually, all the way to Jetty 6.x)

[joakime]

Opened PR #10209 to show that this is possible, but with the added knowledge that when you have an XML focused deployable, you need to tell the system what environment it belongs to.

In other words, your eventual ${jetty.base} will look like this ...

${jetty.base}
├── resources/
│   └── jetty-logging.properties
├── start.d/
│   ├── ee10-deploy.ini
│   ├── ee10-webapp.ini
│   └── http.ini
├── wars/
│   └── demo.war
├── webapps/
│   ├── demo.properties
│   └── demo.xml
└── work/

The ${jetty.base}/webapps/demo.xml points to the war in ${jetty.base}/wars/demo.war (a directory that Jetty doesn't know about or scan for)

And (crucially) the needed file ${jetty.base}/webapps/demo.properties has one important entry ...

environment=ee10

From there, your XML will deploy in the appropriate environment (eg: ee8 / ee9 / ee10).

[gregw]

@alitokmen thanks for following us from 6 to 12! Can you deploy your XML now with the extra info here?

I wonder if we need to work on (edit: s/better/an/) error message if no provider deploys something in webapps?

[joakime]

The core in ScanningAppProvider.createApp() is handling the environment selection currently.

https://github.com/eclipse/jetty.project/blob/jetty-12.0.x/jetty-core/jetty-deploy/src/main/java/org/eclipse/jetty/deploy/providers/ScanningAppProvider.java#L145C1-L203

When it cannot find a webap, or a webapp dir, or a default environment isn't specified, then that app gets ignored (currently logged at DEBUG level).

Proposal for 12.0.1 release.

1. Introduce a means to discover the environment from the XML
2. Perhaps create a new Configure_10.dtd that allows for <Configure environment="ee10" class="org.eclipse.jetty.ee10.webapp.WebAppContext"> style configuration
3. Introduce some basic discovery of the environment from the class name pattern (eg: the package on the <Configure class="org.eclipse.jetty.<env>..." could be used)
4. If no environment is specified, or discovered, for the App, produce a warning.
5. If environment is specified, but there's no active support for that environment, produce a warning. (eg: the App declares ee8 but there's no ee8 environment initialized / specified. likely because the admin hasn't enabled any ee8 modules)

[alitokmen]

Dear @gregw and @joakime

Thank you for your close attention and hints, and thank you for keeping on giving me (and many others) excellent reasons to continue since Jetty 6 🥇

My feedback:

1. The .properties file is a trick I didn't know about, and I am very happy to inform that it indeed does the job! Thanks a lot! (and perhaps it is a good update for https://eclipse.dev/jetty/documentation/jetty-12/operations-guide/index.html#og-deploy-jetty so that this is well known)
2. I am unsure why the environment="ee10" would be needed in the XML, as the WebAppContext already needs to be EE-specific (in the example, org.eclipse.jetty.ee10.webapp.WebAppContext)

With the #1 hint functioning, I am happy to check in codehaus-cargo/cargo@e550652 on Codehaus Cargo for it to support Jetty 12.x further.

Warm regards - and thanks again for your help!

[joakime]

2. I am unsure why the environment="ee10" would be needed in the XML, as the WebAppContext already needs to be EE-specific (in the example, org.eclipse.jetty.ee10.webapp.WebAppContext)

We cannot rely on the <Configure class="<classname>" class name alone, as there are many projects that override / replace / extend / mangle / original work the handlers and could easily have something like ...

<Configure class="org.otherfoundation.rest.jetty.AuditWebAppContext">

That's why there should probably be a fallback to having the environment="ee10" attribute too.

[joakime]

I've been toying with the idea of a @JettyEnv annotation that we can use provide metadata on what environment the (context)handler needs/requires, something the XmlConfiguration and/or start.jar could use to figure things out.

Eg:

package org.eclipse.jetty.ee10.webapp;

@JettyEnv("ee10")
@ManagedObject("Web Application ContextHandler")
public class WebAppContext extends ServletContextHandler implements WebAppClassLoader.Context, Deployable

[alitokmen]

Thank you very much, @joakime

As the updates are going beyond the scope of my initial inquiry, we can either close this ticket or I can provide a different initial description, when it helps with the overall tracking and transparency

[gregw]

In the short term, let's improve our documentation for deployment. Let's open other issues for a) better ways to detect environment; b) what to do if no matching provider is found.

[joakime]

The documentation contains details about the properties files - https://eclipse.dev/jetty/documentation/jetty-12/operations-guide/index.html#og-deploy-jetty

The DEBUG about a missing environment is now a WARN due to PR #10321, which is merged.

Closing as completed.