Web Application Deployment

The Jetty server supports the deployment of these types of web applications:

In the following, the term "web application" is used to refer to either a Jetty Static web application, or Jetty Core web application, or Jetty ContextHandler web application, or Java EE 8 web application or Jakarta EE 9 to Jakarta EE 11 web application, unless specified otherwise.

Also, in the following, references to "Jakarta EE" refer to both Java EE and Jakarta EE, unless specified otherwise.

The Jetty server deploys each web application to a specific environment.

The available environments are:

  • The static environment, for Jetty Static web applications.

  • The core environment, for Jetty Core web applications, and Jetty ContextHandler web applications.

  • The ee{8,9,10,11} environments, for Jakarta EE web applications.

You can simultaneously deploy an old Java EE 8 web application, say old-ee8.war, alongside a new Jakarta EE 11 web application, say new-ee11.war, alongside a web application that only uses the Jetty Core Handler APIs, say backoffice-core.xml, all in the same Jetty server.

For each specific environment there is a specific deploy module that must be enabled:

Each of these modules provides environment specific features, such as library dependencies and default configuration. The Jakarta EE deploy modules provide the corresponding Jakarta EE APIs and the Jetty implementation of those APIs.

For example, you can enable the ee11-deploy module in the following way:

$ java -jar $JETTY_HOME/start.jar --add-modules=ee11-deploy

All deploy modules depend on the deployment-scanner module, that scans monitored directories for web applications to deploy, and for environment configuration files to process.

While you can have many deploy modules enabled, one for each environment, there is only one deployment-scanner module that scans the monitored directories.

By default, for security reasons, web applications are only deployed at server startup from the $JETTY_BASE/webapps directory.

However, you can configure the deployment-scanner module to deploy web applications from a different deploy directory, and/or to deploy/undeploy web applications as they are moved to/removed from the deploy directory (hot deployment).

Monitored Directories

The deployment-scanner module scans the web applications deploy directory specified by the jetty.deploy.webappsDir property, by default $JETTY_BASE/webapps, for web applications to deploy.

The directory specified by the jetty.deploy.environmentsDir property, by default $JETTY_BASE/environments, is also scanned for configuration files that apply to each environment, and therefore to all web applications deployed to that environment.

Web Application Files

A web application basefile can be:

  • A Jetty context XML file, for Jetty Static, Jetty Core and Jakarta EE web applications.

  • A *.war file, for Jakarta EE web applications.

  • A directory, for Jetty Static, Jetty Core and Jakarta EE web applications.

A web application has a basename derived either from the basefile described above, that is either from the Jetty context XML file name, from the *.war file name, or from the directory name.

For example, for the Jetty context XML file old-site.xml, the web application basename is old-site. For the file myapp.war, the basename is myapp. For the directory shop-app/ the basename is shop-app.

Web applications may have an associated <basename>.properties configuration file, for example old-site.properties or shop-app.properties.

This <basename>.properties file contains properties that influence the deployment of the web application, for example by declaring its environment, as described in this section.

A web application <basename>.properties configuration file can specify the following properties:

  • environment=<environment>, to specify the web application environment.

  • jetty.deploy.contextPath=<contextPath>, to specify the web application contextPath (see also this section).

  • jetty.deploy.baseResource=<pathToBaseResource>, to specify the web application base resource directory. The web application base resource directory can be outside of $JETTY_BASE/webapps.

  • jetty.deploy.baseResource.dirAllowed=<true|false>, to specify whether directory listing for the base resource directory is allowed (by default true).

Web Application Format

Jakarta EE Web Application Format

For Jakarta EE web applications, the deployment unit is the usual *.war file or a directory with a *.war structure.

Like for the Jetty Core web application format, the *.war file or a directory can contain an optional in-application Jetty context XML file under the WEB-INF directory, that allows you to configure the web application deployment.

Jetty Core Web Application Format

For Jetty Core web applications, the web application format is a directory with the following structure:

core-app
├── static         # Static files are served from this directory.
│   ├── css
│   │   └── styles.css
│   └── index.html
├── classes        # Where web application Java classes reside.
│   └── com
│       └── acme
│           └── AcmeHandler.class
├── lib            # Where web application Java libraries reside.
│   └── acme-util.jar
└── jetty-web.xml  # Web application specific configuration.

The structure is similar to that of a *.war file.

A notable difference with *.war files is that static files are only served from the static/ directory (with the static/ prefix removed). This means that files in the directory root, or under any other directory that is not static/, are hidden and if requested they will result in a 404 Not Found response. If the static/ directory is missing, then no static files can be served, and therefore all requests are processed dynamically by the Handlers configured in the web application.

Since static files can only be served from the static/ directory, the classes/ and lib/ directories are implicitly hidden, as well as any other directory such as includes/ or fragments/, and any file in the directory root.

The classes/ directory stores the web application’s *.class files, while the lib/ directory stores the web application’s libraries, typically *.jar files. Both these directories are optional.

The jetty-web.xml file is an optional in-application Jetty context XML file, that allows you to configure the web application deployment.

Jetty ContextHandler Web Application Format

For Jetty ContextHandler web applications, the web application format is just a Jetty XML file, that contains references to Jetty Handlers shipped with the Jetty libraries. Refer to this section for the available Jetty Handlers.

For example, you can use MovedContextHandler to redirect an old issue-tracking website at bugs.acme.org to the new issue-tracking website at github.com:

$JETTY_BASE/webapps
└── bugs.acme.org.xml
bugs.acme.org.xml
<?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.server.handler.MovedContextHandler">
  <Set name="virtualHosts">
    <Array type="string"><Item>bugs.acme.org</Item></Array>
  </Set>
  <Set name="contextPath">/</Set>
  <Set name="redirectURI">https://github.com/acme/acme/issues</Set>
  <Set name="statusCode">301</Set>
  <Set name="discardPathInContext">true</Set>
  <Set name="discardQuery">true</Set>
</Configure>

In the example above, file $JETTY_BASE/webapps/bugs.acme.org.xml specifies a web application deployed under virtual host bugs.acme.org at context path /.

The web application is a MovedContextHandler that redirects with HTTP status code 301 (a permanent redirect).

Every request to http://bugs.acme.org/<any-path-or-query> will be redirected to https://github.com/acme/acme/issues.

Another example is the use of ContextHandler in conjunction with RewriteHandler to rewrite old documentation URIs to new documentation URIs:

$JETTY_BASE/webapps
└── docs.project.org.xml
docs.project.org.xml
<?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.server.handler.ContextHandler">
  <Set name="virtualHosts">
    <Array type="string"><Item>docs.project.org</Item></Array>
  </Set>
  <Set name="contextPath">/</Set>
  <Set name="handler">
    <New class="org.eclipse.jetty.rewrite.handler.RewriteHandler">
      <Call name="addRule">
        <Arg>
          <New class="org.eclipse.jetty.rewrite.handler.RewriteRegexRule">
            <Set name="pattern">/docs/#_(.*)</Set>
            <Set name="">/$1</Set>
          </New>
        </Arg>
      </Call>
    </New>
  </Set>
</Configure>

In the example above, file $JETTY_BASE/webapps/docs.project.org.xml specifies a web application deployed under virtual host docs.project.org at context path /.

The web application is a ContextHandler with a child RewriteHandler that rewrites old documentation URIs such as /docs/#_proj-intro to /proj-intro using a regular expression rewrite rule.

Jetty Static Web Application Format

For Jetty Static web applications, the web application format is just a directory, and any file in that directory and any subdirectory is served when requested with the proper request URI — no files are hidden.

For example, with the following directory structure:

$JETTY_BASE/webapps
└── static-app
    ├── css/
    │   └── styles.css
    └── index.html

Requests to http://localhost:8080/static-app/index.html and http://localhost:8080/static-app/css/style.css will serve the correspondent files.

A request to http://localhost:8080/static-app/css/ will list the content of the directory.

To disable directory listing, create a web application properties file with the following content:

static-app.properties
# Specifies the environment.
environment=static

# Disables directory listing.
jetty.deploy.baseResource.dirAllowed=false

Hot vs Cold Deployment

You can configure the deployment-scanner module to scan the monitored directories every N seconds, where N is configured via the jetty.deploy.scanInterval property.

By default, the scan interval is 0 seconds, which means cold deployment, where the scanning is only performed once, at server startup. This means that to deploy a new web application, or redeploy/undeploy an existing web application, you will need to stop and restart the Jetty server.

Setting the scan interval to a value greater than zero means that hot deployment is enabled. The monitored directories are scanned periodically for file changes.

When a file is added/changed/removed from the web applications deploy directory (by default $JETTY_BASE/webapps), then the correspondent web application is processed for deploy/redeploy/undeploy with the deployment rules detailed below.

When a file is added/changed/removed from the environments directory (by default $JETTY_BASE/environments), the file is processed and all web applications deployed to that specific environment are redeployed.

The following command line enables hot deployment by specifying the jetty.deploy.scanInterval property on the command line, and therefore only for this particular run:

$ java -jar $JETTY_HOME/start.jar jetty.deploy.scanInterval=5

To make hot deployment configuration persistent, you need to edit the $JETTY_BASE/start.d/deployment-scanner.ini module configuration file, and uncomment the property jetty.deploy.scanInterval and change the value to 5 seconds:

deployment-scanner.ini
--module=deployment-scanner

jetty.deploy.scanInterval=5
...

When hot deployment is enabled, the scanner may detect changes to multiple files, and will process the changes in the following way:

  • Undeploy the web applications that have been removed, if any, in basename reverse alphabetical order.

  • Redeploy the web applications that have been modified, if any, in basename alphabetical order.

  • Deploy the web applications that have been added, if any, in basename alphabetical order.

Deployment Rules

For cold deployment, the presence of a web application basefile causes its deployment at server startup.

For hot deployment the following rules apply:

  • Adding a new web application basefile that refers to a new basename to the web applications deploy directory (by default $JETTY_BASE/webapps) causes the deployment of the new web application. For example, adding mywebapp.war to an empty $JETTY_BASE/webapps.

  • Adding a new web application basefile (such as mywebapp.xml), or a web application properties file (such as mywebapp.properties) to the web applications deploy directory that refers to an existing basename causes the redeployment of the web application. For example, adding mywebapp.xml or mywebapp.properties when mywebapp.war already exists.

  • Changing a file that refers to a basename causes the redeployment of the web application. For example, editing or changing mywebapp.xml, mywebapp.war or mywebapp.properties.

  • Removing some, but not all, of the files that refer to the same basename causes the redeployment of the web application. For example, removing mywebapp.xml or mywebapp.properties, but leaving mywebapp.war.

  • Removing all the files that refer to the same basename causes the undeployment of the web application. For example, removing mywebapp.xml, mywebapp.war and mywebapp.properties.

When a web application is deployed as a directory (not as a file), it is not possible to change the directory (for example using the touch command) to cause the redeployment of the web application. Modification of the files inside the web application directory is not detected as a change. You must add at least a <basename>.properties file (even empty), and touch it to cause redeployment.

In the presence of multiple web application basefiles that refers to the same basename, for example when both mywebapp.xml and mywebapp.war exist, or when both mywebapp.war and mywebapp/ exist, then the following rules apply:

  • If <basename>.xml exists, it has precedence over <basename>.war and <basename>/, so only <basename>.xml will be considered for deployment. This allows the XML file to reference the *.war file or directory and avoid that the web application is deployed twice.

  • Otherwise, if <basename>.war exists, it has precedence over <basename>/, so only the *.war file will be considered for deployment. This allows the directory with the same basename to be the *.war file unpack location and avoid that the web application is deployed twice.

  • Otherwise, <basename>/ exists and will be considered for deployment.

Context Path Resolution

When a web application is deployed (or redeployed), the web application contextPath is derived from the web application files, with the following rules:

  • If <basename>.xml exists, it is processed and the directives contained in the XML file can set the contextPath to any value (including one that is different from the basename).

  • If <basename>.properties exists, then the contextPath is set to the value of the jetty.deploy.contextPath property, if it is present in <basename>.properties.

  • If the basename is ROOT, case-insensitive, the contextPath is /, and the web application is reachable at http://localhost:8080/.

  • Otherwise, the contextPath is the basename, and the web application is reachable at http://localhost:8080/<basename>.

Environment Resolution

A web application is always deployed to a specific environment, which is either configured explicitly for the web application or set to the default environment.

You must always enable at least one deploy module, otherwise no web application can be deployed.

Single Deployer Environment Resolution

If only a single specific deploy module is enabled, for example ee11-deploy, then its environment is the default environment and applications will be deployed to that environment without any additional configuration.

If a web application properties file exists, and it specifies the environment property, then its value must specify the same environment as the deploy module, otherwise the deployment will fail.

Make sure that you do not inadvertently mix a deploy module for one environment with a web application of a different environment.

For example, if you have a Jetty core web application in directory core-app/, and you enable the static-deploy module, then the core-app/ directory will be interpreted as a static web application, and files from the core-app/classes/ directory (that are normally hidden and not served) will be served as static files.
It is good practice to always specify the web application properties file and specify the environment property, to avoid deployment of your web applications to an unexpected environment.

Multiple Deployers Environment Resolution

If multiple deployer modules are enabled, then the default environment is (in order):

  • The most recent Jakarta EE environment of the ee{8,9,10,11}-deploy modules that are enabled, if any.

  • Otherwise, the core environment, if the core-deploy module is enabled.

  • Otherwise, the static environment, if the static-deploy module is enabled.

For example, if core-deploy, ee9-deploy and the ee11-deploy modules are enabled, then ee11 is the default environment, to which applications will be deployed unless otherwise configured (see below).

To configure a specific environment for an application, you add a web application properties file and specify the environment property.

For example, an application deployed to $JETTY_BASE/webapps/my-ee9-app.war is configured with the file $JETTY_BASE/webapps/my-ee9-app.properties, with the following content:

my-ee9-app.properties
environment=ee9
In case of multiple deploy environments, it is good practice to always specify the web application properties file for your web applications, and specify the environment property, to avoid deployment of your web applications to an unexpected environment.

If you do not specify the environment property in the web application properties file for your web applications, then the deployer for the default environment will be used.

For example, if the ee11-deploy and the ee9-deploy module are enabled, and you deploy a Jakarta EE 9 web application without the *.properties file, then it will be deployed to the (default) ee11 environment, with unspecified results.

This unspecified deployment may not work as the Jakarta EE 9 web application may use APIs that have been removed in EE 11, causing an error at runtime.

Also in case of multiple deployers, if a web application properties file specifies an environment property, and the corresponding deploy module is not enabled, the deployment will fail.

Deploying Jetty Context XML Files

A Jetty context XML file is a Jetty XML file that allows you to customize the deployment of web applications.

Recall that the deployment rules give priority to Jetty context XML files over *.war files or directories.

To deploy a web application using a Jetty context XML file, simply place the Jetty context XML file in the $JETTY_BASE/webapps directory.

For example, to deploy a Jakarta EE 11 web application, enable the ee11-deploy module, and add the following Jetty context XML file, named wiki.xml:

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

<Configure class="org.eclipse.jetty.ee11.webapp.WebAppContext"> (1)
  <Set name="contextPath">/wiki</Set> (2)
  <Set name="war">/opt/myapps/myapp.war</Set> (3)
</Configure>
1 Configures a WebAppContext, which is the Jetty component that represents a standard Servlet web application for Jakarta EE 11.
2 Specifies the web application contextPath, which may be different from the basename derived from wiki.xml.
3 Specifies the file system path of the *.war file (which may be external to $JETTY_BASE).

The Jetty context XML file may be accompanied by a web application properties file that specifies the environment to use for the deployment:

wiki.properties
environment=ee11

Refer to this section for more information about specifying the environment.

The $JETTY_BASE directory would look like this:

$JETTY_BASE
├── resources
│   └── jetty-logging.properties
├── start.d
│   ├── ...
│   ├── ee11-deploy.ini
│   └── http.ini
└── webapps
    ├── wiki.properties
    └── wiki.xml
The *.war file may be placed anywhere in the file system and does not need to be placed in the $JETTY_BASE/webapps directory, as long as you have a Jetty context XML file referencing it.
If you place both the Jetty context XML file and the *.war file in the $JETTY_BASE/webapps directory, remember that they must produce the same basename, for example wiki.xml and wiki.war, so that the deployment is performed only once using the Jetty context XML file (and not the *.war file).

You can use the features of Jetty XML files to avoid to hard-code file system paths or other configurations in your Jetty context XML files, for example by using properties declared in wiki.properties or JVM system properties:

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

<Configure class="org.eclipse.jetty.ee11.webapp.WebAppContext">
  <Set name="contextPath"><Property name="wiki.contextPath"/></Set>
  <Set name="war"><SystemProperty name="webapps.dir"/>/myapp.war</Set>
</Configure>

Note how the contextPath is obtained from the wiki.contextPath configuration property (as an alternative to the jetty.deploy.contextPath property specified in this section), while *.war file path is obtained by resolving the system property webapps.dir that you can specify on the command line when you start Jetty:

wiki.properties
environment=ee11
wiki.contextPath=/wiki
$ java -jar $JETTY_HOME/start.jar -Dwebapps.dir=/opt/myapps

Properties specified in environment properties file (described in this section) and in the web application properties file (described in this section) are available when processing the Jetty context XML file.

Remember that Jetty context XML files in the $JETTY_BASE/webapps directory can only refer to classes present in the environment class-path/module-path, in the server class-path/module-path, and in the JVM class-path/module-path. For more information about the Jetty class loader hierarchy, see this section.

If you need to configure the deployment of your web application referring to web application specific classes, use the in-application Jetty context XML file, as described in this section.

Environment Configuration

Environments can be configured via Jetty XML files or *.properties files placed in the $JETTY_HOME/environments directory.

Each environment configuration is applied to all web applications deployed/redeployed to that environment.

The environment configuration files must start with the environment name, and are processed in alphabetical order, for example ee11.xml, ee11-extra.xml and ee11-other.xml are processed in this order, and they all affect the ee11 environment. The same holds for *.properties files.

The environment-specific Jetty XML files will be applied to the web application before any Jetty context XML file associated with the web application, present in the $JETTY_HOME/webapps directory.

The contents of the environment specific Jetty context XML file may only contain references to classes appropriate for that environment.

For example, you can have a $JETTY_HOME/environments/ee11.xml file with the following content:

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

<Configure class="org.eclipse.jetty.ee11.webapp.WebAppContext">
  <Call name="setAttribute">
    <Arg>com.acme.ee11.feature</Arg>
    <Arg>value</Arg>
  </Call>
</Configure>

The $JETTY_HOME/environments/ee11-extra.xml file may contain:

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

<Configure class="org.eclipse.jetty.ee11.webapp.WebAppContext">
  <Call name="addEventListener">
    <Arg>
      <New class="com.acme.MyListenerFeature"/>
    </Arg>
  </Call>
</Configure>

Custom classes like com.acme.MyListenerFeature must be present in the environment class loader, so that the XML file can reference them. You can extend the environment class loader by enabling the ee11-ext.mod. Refer to this section for more information about the Jetty class loader hierarchy.

The directory structure would look like this:

$JETTY_BASE
├── environments
│   ├── ee11.xml
│   └── ee11-extra.xml
├── start.d
│   ├── ...
│   └── ee11-ext.ini
└── webapps
    ├── wiki.properties
    └── wiki.xml

In-Application Jetty Context XML File

As discussed in this section, the deployment of a web application can be specified with a Jetty context XML file placed in the $JETTY_HOME/webapps directory.

However, the deployment of a web application can also be configured using a Jetty context XML file placed inside the web application, both for Core web application deployments and Jakarta EE web application deployments.

This file can be useful:

  • To place all configuration inside your web application archive.

  • To perform configuration of the web application that can only occur after the web application’s class-path has been created, for example because it references classes present in web application itself.

In-Application Jetty Context XML File for Core Web Application Deployments

The file must be in the root of the web application and named jetty-web.xml, see this section for an example.

In-Application Jetty Context XML Files for Jakarta EE Web Application Deployments

For Jakarta EE deployments, there may be multiple in-application Jetty context XML files, typically one for each ee{8,9,10,11} environment.

The files must be named either WEB-INF/jetty-ee{8,9,10,11}-web.xml or WEB-INF/jetty-web.xml; the latter is only processed if the former(s) are missing.

It is good practice to name the file according to the environment into which the web application will be deployed.

If your web application can be deployed to multiple environments, then you should include a WEB-INF/jetty-ee{8,9,10,11}-web.xml file for each environment.

If you only deploy to a single environment, then you can omit it from the filename and use WEB-INF/jetty-web.xml, but be aware that likely you will not be able to deploy the web application to a different environment without updating the contents of the file.

Configuring JNDI Entries

Web applications may reference JNDI entries, such as a JDBC DataSource or a Jakarta Mail Session.

The JNDI entries must be defined in a Jetty context XML file, as detailed in this section.

Configuring Virtual Hosts

A virtual host is an internet domain name, registered in the Domain Name Server (DNS), for an IP address such that multiple virtual hosts will resolve to the same IP address of a single server instance.

If you have multiple web applications deployed on the same Jetty server, by using virtual hosts you will be able to target a specific web application.

For example, you may have a web application for your business and a web application for your hobbies , both deployed in the same Jetty server. By using virtual hosts, you will be able to have the first web application available at http://domain.biz/, and the second web application available at http://hobby.net/.

Another typical case is when you want to use different subdomains for different web application, for example a project website is at http://project.org/ and the project documentation is at http://docs.project.org.

Virtual hosts can be used with any context that is a subclass of ContextHandler, and therefore for Jetty Static web applications, Jetty Core web applications and Jakarta EE web applications.

Virtual Host Names

Jetty supports the following variants to be specified as virtual host names:

www.hostname.com

A fully qualified domain name. It is important to list all variants as a site may receive traffic for both www.hostname.com and hostname.com.

*.hostname.com

A wildcard domain name which will match only one level of arbitrary subdomains. The wildcard domain *.foo.com will match www.foo.com and m.foo.com, but not www.other.foo.com.

10.0.0.2

An IP address may be set as a virtual host to indicate that a web application should handle requests received on the network interface with that IP address. This is typically only used for protocols that do not indicate a host name such as HTTP/0.9 or HTTP/1.0.

@<ConnectorName>

A Jetty server Connector name to indicate that a web application should handle requests received on the server Connector with that name, and therefore received on a specific socket address, either an IP port for ServerConnector, or a Unix-Domain path for UnixDomainServerConnector (see also this section).

www.√integral.com

Non-ASCII and IDN domain names can be set as virtual hosts using Puny Code equivalents that may be obtained from a Punycode/IDN converters. For example if the non-ASCII domain name www.√integral.com is given to a browser, then the browser will make a request that uses the domain name www.xn—​integral-7g7d.com, which is the name that should be added as the virtual host name.

Virtual Hosts Configuration

If you have a web application mywebapp.war you can configure its virtual hosts in this way:

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

<Configure class="org.eclipse.jetty.ee11.webapp.WebAppContext">
  <Set name="contextPath">/mywebapp</Set>
  <Set name="war">/opt/webapps/mywebapp.war</Set>
  <Set name="virtualHosts">
    <Array type="java.lang.String">
      <Item>mywebapp.com</Item>
      <Item>www.mywebapp.com</Item>
      <Item>mywebapp.net</Item>
      <Item>www.mywebapp.net</Item>
    </Array>
  </Set>
</Configure>

Your web application will be available at:

  • http://mywebapp.com/mywebapp

  • http://www.mywebapp.com/mywebapp

  • http://mywebapp.net/mywebapp

  • http://www.mywebapp.net/mywebapp

In the example above, the web application contextPath is configured to /mywebapp.

As such, a request to http://mywebapp.com/other will not match your web application because the contextPath does not match.

Likewise, a request to http://other.com/mywebapp will not match your web application because the virtual host does not match.

Same Context Path, Different Virtual Hosts

If you want to deploy different web applications to the same context path, typically the root context path /, you must use virtual hosts to differentiate among web applications.

You have domain.war that you want to deploy at http://domain.biz/ and hobby.war that you want to deploy at http://hobby.net.

To achieve this, you simply use the same context path of / for each of your web applications, while specifying different virtual hosts for each of your web applications:

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

<Configure class="org.eclipse.jetty.ee11.webapp.WebAppContext">
  <Set name="contextPath">/</Set>
  <Set name="war">/opt/webapps/domain.war</Set>
  <Set name="virtualHosts">
    <Array type="java.lang.String">
      <Item>domain.biz</Item>
    </Array>
  </Set>
</Configure>
hobby.xml
<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE Configure PUBLIC "-//Jetty//Configure//EN" "https://jetty.org/configure_10_0.dtd">

<Configure class="org.eclipse.jetty.ee11.webapp.WebAppContext">
  <Set name="contextPath">/</Set>
  <Set name="war">/opt/webapps/hobby.war</Set>
  <Set name="virtualHosts">
    <Array type="java.lang.String">
      <Item>hobby.net</Item>
    </Array>
  </Set>
</Configure>

Different Port, Different Web Application

Sometimes it is required to serve different web applications from different socket addresses (either different IP ports, or different Unix-Domain paths), and therefore from different server Connectors.

For example, you want requests to http://localhost:8080/ to be served by one web application, but requests to http://localhost:9090/ to be served by another web application.

This configuration may be useful when Jetty sits behind a load balancer.

In this case, you want to configure multiple connectors, each with a different name specified with https://javadoc.jetty.org/jetty-12.1/org/eclipse/jetty/server/AbstractConnector.html#setName(java.lang.String), and then reference the connector name in the web application virtual host configuration:

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

<Configure class="org.eclipse.jetty.ee11.webapp.WebAppContext">
  <Set name="contextPath">/</Set>
  <Set name="war">/opt/webapps/domain.war</Set>
  <Set name="virtualHosts">
    <Array type="java.lang.String">
      <Item>@port8080</Item>
    </Array>
  </Set>
</Configure>
hobby.xml
<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE Configure PUBLIC "-//Jetty//Configure//EN" "https://jetty.org/configure_10_0.dtd">

<Configure class="org.eclipse.jetty.ee11.webapp.WebAppContext">
  <Set name="contextPath">/</Set>
  <Set name="war">/opt/webapps/hobby.war</Set>
  <Set name="virtualHosts">
    <Array type="java.lang.String">
      <Item>@port9090</Item>
    </Array>
  </Set>
</Configure>

Web application domain.war has a virtual host of @port8080, where port8080 is the name of a Jetty connector.

Likewise, web application hobby.war has a virtual host of @port9090, where port9090 is the name of another Jetty connector.

See this section for further information about how to configure connectors.

Configuring *.war File Extraction

By default, when a Jakarta EE web application in *.war file format is deployed, the *.war file is uncompressed and its content extracted in a temporary directory. The web application resources are served by Jetty from the files extracted in the temporary directory, not from the files within the *.war file, for performance reasons.

If you do not want Jetty to extract the *.war files, you can disable this feature in this way:

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

<Configure class="org.eclipse.jetty.ee11.webapp.WebAppContext">
  <Set name="contextPath">/mywebapp</Set>
  <Set name="war">/opt/webapps/mywebapp.war</Set>
  <Set name="extractWAR">false</Set>
</Configure>

Overriding web.xml

When deploying Jakarta EE web applications, you can configure an additional web.xml that complements the web.xml file that is present in the web application *.war file. This additional web.xml is processed after the *.war file web.xml. This allows you to add host specific configuration or server specific configuration without having to extract the web application web.xml, modify it, and repackage it in the *.war file.

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

<Configure class="org.eclipse.jetty.ee11.webapp.WebAppContext">
  <Set name="contextPath">/mywebapp</Set>
  <Set name="war">/opt/webapps/mywebapp.war</Set>
  <Set name="overrideDescriptor">/opt/webapps/mywebapp-web.xml</Set>
</Configure>

The format of the additional web.xml is exactly the same as a standard web.xml file, for example:

mywebapp-web.xml
<?xml version="1.0" encoding="UTF-8"?>
<web-app xmlns="http://xmlns.jcp.org/xml/ns/javaee"
         xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
         xsi:schemaLocation="https://jakarta.ee/xml/ns/jakartaee https://jakarta.ee/xml/ns/jakartaee/web-app_6_1.xsd"
         version="6.1">
  <servlet>
    <servlet-name>my-servlet</servlet-name>
    <init-param>
      <param-name>host</param-name>
      <param-value>192.168.0.13</param-value>
    </init-param>
  </servlet>
</web-app>

In the example above, you configured the my-servlet Servlet (defined in the web application web.xml), adding a host-specific init-param with the IP address of the host.