Updated deploy documentation.
Signed-off-by: Simone Bordet <simone.bordet@gmail.com>
This commit is contained in:
Simone Bordet
parent
601bd687aa
commit
85407aabdb
|
|
@ -2,7 +2,7 @@
|
|||
// See https://github.com/asciidoctor/asciidoctor-intellij-plugin/wiki/Support-project-specific-configurations
|
||||
:ee-all: ee{8,9,10}
|
||||
:ee-current: ee10
|
||||
:ee-current-caps: EE10
|
||||
:ee-current-caps: EE 10
|
||||
:experimental:
|
||||
:imagesdir: images
|
||||
:jetty-home: ../../../../../../../jetty-home/target/jetty-home
|
||||
|
|
|
|||
|
|
@ -18,9 +18,17 @@ You can deploy two types of web application resources with Jetty:
|
|||
|
||||
* *Standard Web Application Archives*, in the form of `+*.war+` files or web application directories, defined by the link:https://www.oracle.com/java/technologies/java-servlet-tec.html[Servlet specification].
|
||||
Their deployment is described in xref:og-begin-deploy-war[this section].
|
||||
* *Jetty context XML files*, that allow you to customize the deployment of standard web applications, and also allow you use Jetty components -- and possibly custom components written by you -- to assemble your web applications.
|
||||
* *Jetty context XML files*, that allow you to customize the deployment of standard web applications, and also allow you to use Jetty components -- and possibly custom components written by you -- to assemble your web applications.
|
||||
Their deployment is described in xref:og-deploy[this section].
|
||||
|
||||
Jetty supports the deployment of both standard web applications and Jetty context XML files in a specific _environment_.
|
||||
|
||||
In the following sections you can find simple examples of deployments of Jakarta {ee-current-caps} web applications.
|
||||
|
||||
However, Jetty supports simultaneous deployment of web applications each to a possibly different environment, for example an old Java EE 8 web application alongside a new Jakarta {ee-current-caps} web application.
|
||||
|
||||
Refer to the section about xref:og-deploy[deployment] for further information about how to deploy to different environments.
|
||||
|
||||
[[og-begin-deploy-war]]
|
||||
===== Deploying +*.war+ Files
|
||||
|
||||
|
|
@ -48,7 +56,12 @@ mywebapp.war
|
|||
|
||||
To deploy a standard web application, you need to enable the xref:og-module-eeN-deploy[`{ee-current}-deploy` module].
|
||||
|
||||
NOTE: The following examples assume you're deploying a Jakarta {ee-current-caps} application; for other versions of Jakarta EE, make sure to activate the corresponding `{ee-all}-deploy` module.
|
||||
[NOTE]
|
||||
====
|
||||
The following examples assume you're deploying a Jakarta {ee-current-caps} application; for other versions of Jakarta EE, make sure to activate the corresponding `{ee-all}-deploy` module.
|
||||
|
||||
Refer to the section about xref:og-deploy[deployment] for further information about how to deploy to different environments.
|
||||
====
|
||||
|
||||
[subs=attributes]
|
||||
----
|
||||
|
|
|
|||
|
|
@ -14,12 +14,31 @@
|
|||
[[og-deploy]]
|
||||
=== Web Application Deployment
|
||||
|
||||
Most of the times you want to be able to customize the deployment of your web applications, for example by changing the `contextPath`, or by adding JNDI entries, or by configuring virtual hosts, etc.
|
||||
Most of the time you want to be able to customize the deployment of your web applications, for example by changing the `contextPath`, or by adding JNDI entries, or by configuring virtual hosts, etc.
|
||||
|
||||
The customization is performed by the xref:og-module-eeN-deploy[`{ee-all}-deploy` module] by processing xref:og-deploy-jetty[Jetty context XML files].
|
||||
Jetty supports the deployment of each web application to a specific _environment_.
|
||||
The available environments are:
|
||||
|
||||
* Java EE 8 -- Supports Servlet 4.0 (and associated specifications) in the `+javax.*+` packages.
|
||||
* Jakarta EE 9 -- Supports Servlet 5.0 (and associated specifications) in the `+jakarta.*+` packages.
|
||||
* Jakarta EE 10 -- Supports Servlet 6.0 (and associated specifications) in the `+jakarta.*+` packages.
|
||||
* Jetty core -- Supports web applications written against the Jetty `Handler` APIs, without any Servlet dependencies.
|
||||
|
||||
This means that you can simultaneously deploy an old Java EE 8 web application, say `old-ee8.war`, alongside a new Jakarta {ee-current-caps} web application, say `new-{ee-current}.war`, alongside a web application that only uses the Jetty `Handler` APIs, say `app-jetty.xml`.
|
||||
|
||||
The customization is performed by processing xref:og-deploy-jetty[Jetty context XML files].
|
||||
|
||||
The `deploy` module contains the `DeploymentManager` component that scans the `$JETTY_BASE/webapps` directory for changes, following the deployment rules described in xref:og-deploy-rules[this section].
|
||||
|
||||
For each specific environment there is a specific deploy module that you must enable:
|
||||
|
||||
* For Java EE 8, xref:og-module-eeN-deploy[`ee8-deploy`]
|
||||
* For Java EE 9, xref:og-module-eeN-deploy[`ee9-deploy`]
|
||||
* For Java {ee-current-caps}, xref:og-module-eeN-deploy[`{ee-current}-deploy`]
|
||||
* For Jetty core, xref:og-module-core-deploy[`core-deploy`]
|
||||
|
||||
Each of these modules provide the environment specific features, and depend on the `deploy` module that provides the scanning features.
|
||||
|
||||
include::deploy-hot-static.adoc[]
|
||||
include::deploy-rules.adoc[]
|
||||
include::deploy-jetty.adoc[]
|
||||
|
|
|
|||
|
|
@ -21,12 +21,12 @@ The web application resources are served by Jetty from the files extracted in th
|
|||
If you do not want Jetty to extract the `+*.war+` files, you can disable this feature, for example:
|
||||
|
||||
.mywebapp.xml
|
||||
[source,xml,highlight=8]
|
||||
[source,xml,highlight=8,subs="verbatim,attributes"]
|
||||
----
|
||||
<?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.ee9.webapp.WebAppContext">
|
||||
<Configure class="org.eclipse.jetty.{ee-current}.webapp.WebAppContext">
|
||||
<Set name="contextPath">/mywebapp</Set>
|
||||
<Set name="war">/opt/webapps/mywebapp.war</Set>
|
||||
<Set name="extractWAR">false</Set>
|
||||
|
|
|
|||
|
|
@ -23,17 +23,17 @@ To deploy a web application using a Jetty context XML file, simply place the fil
|
|||
A simple Jetty context XML file, for example named `wiki.xml` is the following:
|
||||
|
||||
.wiki.xml
|
||||
[source,xml,subs=verbatim]
|
||||
[source,xml,subs="verbatim,attributes"]
|
||||
----
|
||||
<?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.ee9.webapp.WebAppContext"> <1>
|
||||
<Configure class="org.eclipse.jetty.{ee-current}.webapp.WebAppContext"> <1>
|
||||
<Set name="contextPath">/wiki</Set> <2>
|
||||
<Set name="war">/opt/myapps/myapp.war</Set> <3>
|
||||
</Configure>
|
||||
----
|
||||
<1> Configures a link:{javadoc-url}/org/eclipse/jetty/webapp/WebAppContext.html[`WebAppContext`], which is the Jetty component that represents a standard Servlet web application.
|
||||
<1> Configures a link:{javadoc-url}/org/eclipse/jetty/{ee-current}/webapp/WebAppContext.html[`WebAppContext`], which is the Jetty component that represents a standard Servlet web application.
|
||||
<2> Specifies the web application `contextPath`, which may be different from the `+*.war+` file name.
|
||||
<3> Specifies the file system path of the `+*.war+` file.
|
||||
|
||||
|
|
@ -57,12 +57,12 @@ IMPORTANT: If you place both the Jetty context XML file _and_ the `+*.war+` file
|
|||
You can use the features of xref:og-xml[Jetty XML files] to avoid to hard-code file system paths or other configurations in your Jetty context XML files, for example by using system properties:
|
||||
|
||||
.wiki.xml
|
||||
[source,xml]
|
||||
[source,xml,subs="verbatim,attributes"]
|
||||
----
|
||||
<?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.ee9.webapp.WebAppContext">
|
||||
<Configure class="org.eclipse.jetty.{ee-current}.webapp.WebAppContext">
|
||||
<Set name="contextPath">/wiki</Set>
|
||||
<Set name="war"><SystemProperty name="myapps.dir"/>/myapp.war</Set>
|
||||
</Configure>
|
||||
|
|
|
|||
|
|
@ -18,12 +18,12 @@ A web application may _reference_ a JNDI entry, such as a JDBC `DataSource` from
|
|||
The JNDI entry must be _defined_ in a xref:og-jndi-xml[Jetty XML file], for example a context XML like so:
|
||||
|
||||
.mywebapp.xml
|
||||
[source,xml,subs=normal]
|
||||
[source,xml,subs="verbatim,attributes"]
|
||||
----
|
||||
<?xml version="1.0" encoding="UTF-8"?>
|
||||
<!DOCTYPE Configure PUBLIC "-//Jetty//Configure//EN" "https://www.eclipse.org/jetty/configure_10_0.dtd">
|
||||
|
||||
<Configure id="wac" class="org.eclipse.jetty.ee9.webapp.WebAppContext">
|
||||
<Configure id="wac" class="org.eclipse.jetty.{ee-current}.webapp.WebAppContext">
|
||||
<Set name="contextPath">/mywebapp</Set>
|
||||
<Set name="war">/opt/webapps/mywebapp.war</Set>
|
||||
# <New class="org.eclipse.jetty.plus.jndi.Resource">
|
||||
|
|
@ -47,8 +47,8 @@ For more information and examples on how to use JNDI in Jetty, refer to the xref
|
|||
Class `com.mysql.cj.jdbc.MysqlConnectionPoolDataSource` is present in the MySQL JDBC driver file, `mysql-connector-java-<version>.jar`, which must be available on the server's classpath .
|
||||
|
||||
If the class is instead present _within_ the web application, then the JNDI entry must be declared in a `WEB-INF/jetty-env.xml` file - see the xref:og-jndi[JNDI] feature section for more information and examples.
|
||||
|
||||
====
|
||||
|
||||
// TODO: add a link to reference the section about how
|
||||
// to add a JDBC driver jar to the server classpath.
|
||||
|
||||
|
|
|
|||
|
|
@ -19,12 +19,12 @@ 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
|
||||
[source,xml,highlight=8]
|
||||
[source,xml,highlight=8,subs="verbatim,attributes"]
|
||||
----
|
||||
<?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.ee9.webapp.WebAppContext">
|
||||
<Configure class="org.eclipse.jetty.{ee-current}.webapp.WebAppContext">
|
||||
<Set name="contextPath">/mywebapp</Set>
|
||||
<Set name="war">/opt/webapps/mywebapp.war</Set>
|
||||
<Set name="overrideDescriptor">/opt/webapps/mywebapp-web.xml</Set>
|
||||
|
|
@ -39,8 +39,8 @@ The format of the additional `web.xml` is exactly the same as a standard `web.xm
|
|||
<?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="http://xmlns.jcp.org/xml/ns/javaee http://xmlns.jcp.org/xml/ns/javaee/web-app_4_0.xsd"
|
||||
version="4.0">
|
||||
xsi:schemaLocation="https://jakarta.ee/xml/ns/jakartaee https://jakarta.ee/xml/ns/jakartaee/web-app_6_0.xsd"
|
||||
version="6.0">
|
||||
<servlet>
|
||||
<servlet-name>my-servlet</servlet-name>
|
||||
<init-param>
|
||||
|
|
|
|||
|
|
@ -20,19 +20,44 @@ _Updating_ a `+*.war+` file or a Jetty context XML file causes the `DeploymentMa
|
|||
|
||||
_Removing_ a `+*.war+` file, a `+*.war+` directory, a Jetty context XML file or a normal directory from `$JETTY_BASE/webapps` causes the `DeploymentManager` to undeploy the web application, which means that the Jetty context component representing the web application is stopped and removed from the Jetty server.
|
||||
|
||||
[[og-deploy-rules-context-path]]
|
||||
===== Context Path Resolution
|
||||
|
||||
When a file or directory is added to `$JETTY_BASE/webapps`, the `DeploymentManager` derives the web application `contextPath` from the file or directory name, with the following rules:
|
||||
|
||||
* If the directory name is, for example, `mywebapp/`, it is deployed as a standard web application if it contains a `WEB-INF/` subdirectory, otherwise it is deployed as a web application of static content.
|
||||
The `contextPath` would be `/mywebapp` (that is, the web application is reachable at `+http://localhost:8080/mywebapp/+`).
|
||||
* If the directory name is `ROOT`, case insensitive, the `contextPath` is `/` (that is, the web application is reachable at `+http://localhost:8080/+`).
|
||||
* If the directory name is `ROOT`, case-insensitive, the `contextPath` is `/` (that is, the web application is reachable at `+http://localhost:8080/+`).
|
||||
* If the directory name ends with `.d`, for example `config.d/`, it is ignored, although it may be referenced to configure other web applications (for example to store common files).
|
||||
* If the `+*.war+` file name is, for example, `mywebapp.war`, it is deployed as a standard web application with the context path `/mywebapp` (that is, the web application is reachable at `+http://localhost:8080/mywebapp/+`).
|
||||
* If the file name is `ROOT.war`, case insensitive, the `contextPath` is `/` (that is, the web application is reachable at `+http://localhost:8080/+`).
|
||||
* If the file name is `ROOT.war`, case-insensitive, the `contextPath` is `/` (that is, the web application is reachable at `+http://localhost:8080/+`).
|
||||
* If both the `mywebapp.war` file and the `mywebapp/` directory exist, only the file is deployed.
|
||||
This allows the directory with the same name to be the `+*.war+` file unpack location and avoid that the web application is deployed twice.
|
||||
* A xref:og-deploy-jetty[Jetty context XML file] named `mywebapp.xml` is deployed as a web application by processing the directives contained in the XML file itself, which must set the `contextPath`.
|
||||
* A xref:og-deploy-jetty[Jetty context XML file] named `mywebapp.xml` is deployed as a web application by processing the directives contained in the XML file itself, which must set the `contextPath`, which could be different from the name of the XML file.
|
||||
* If both `mywebapp.xml` and `mywebapp.war` exist, only the XML file is deployed.
|
||||
This allows the XML file to reference the `+*.war+` file and avoid that the web application is deployed twice.
|
||||
|
||||
[[og-deploy-rules-environment]]
|
||||
===== Environment Resolution
|
||||
|
||||
A web application is always deployed to a specific environment.
|
||||
|
||||
If you enabled only one specific deployer module, for example `{ee-current}-deploy`, then the web applications and the Jetty context XML files in `$JETTY_BASE/webapps` will be deployed to the `{ee-current}` environment.
|
||||
|
||||
You can enable multiple deployer modules if you need to deploy multiple web applications each to a specific environment.
|
||||
|
||||
For example, you have an `old-ee9.war` web application that you want to deploy to the Jakarta EE 9 environment, and a `new-{ee-current}.war` web application that you want to deploy to the Jakarta {ee-current-caps} environment.
|
||||
First, you must enable both the `ee9-deploy` and the `{ee-current}-deploy` modules.
|
||||
Then, you add a `+*.properties+` file with the same name of the web application, in the example above `$JETTY_BASE/webapps/old-ee9.properties`, with the following content:
|
||||
|
||||
[source,properties]
|
||||
====
|
||||
environment=ee9
|
||||
====
|
||||
|
||||
You may also add a `+*.properties+` file for `new-{ee-current}.war`, but it is not necessary because the most recent environment is used by default.
|
||||
// TODO: verify the statement above. For an ee8 and an ee9 webapp, is it true that ee9 will be used by default (or ee10 will)?
|
||||
|
||||
|
||||
// TODO: add section about the work directory from
|
||||
// old_docs/contexts/temporary-directories.adoc
|
||||
|
|
|
|||
|
|
@ -53,12 +53,12 @@ For example if the non-ASCII domain name `www.√integral.com` is given to a bro
|
|||
|
||||
If you have a web application `mywebapp.war` you can configure its virtual hosts in this way:
|
||||
|
||||
[source,xml]
|
||||
[source,xml,subs="verbatim,attributes"]
|
||||
----
|
||||
<?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.ee9.webapp.WebAppContext">
|
||||
<Configure class="org.eclipse.jetty.{ee-current}.webapp.WebAppContext">
|
||||
<Set name="contextPath">/mywebapp</Set>
|
||||
<Set name="war">/opt/webapps/mywebapp.war</Set>
|
||||
<Set name="virtualHosts">
|
||||
|
|
@ -98,12 +98,12 @@ You have `domain.war` that you want to deploy at `+http://domain.biz/+` and `hob
|
|||
To achieve this, you simply use the same context path of `/` for each of your webapps, while specifying different virtual hosts for each of your webapps:
|
||||
|
||||
.domain.xml
|
||||
[source,xml]
|
||||
[source,xml,subs="verbatim,attributes"]
|
||||
----
|
||||
<?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.ee9.webapp.WebAppContext">
|
||||
<Configure class="org.eclipse.jetty.{ee-current}.webapp.WebAppContext">
|
||||
<Set name="contextPath">/</Set>
|
||||
<Set name="war">/opt/webapps/domain.war</Set>
|
||||
<Set name="virtualHosts">
|
||||
|
|
@ -115,12 +115,12 @@ To achieve this, you simply use the same context path of `/` for each of your we
|
|||
----
|
||||
|
||||
.hobby.xml
|
||||
[source,xml]
|
||||
[source,xml,subs="verbatim,attributes"]
|
||||
----
|
||||
<?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.ee9.webapp.WebAppContext">
|
||||
<Configure class="org.eclipse.jetty.{ee-current}.webapp.WebAppContext">
|
||||
<Set name="contextPath">/</Set>
|
||||
<Set name="war">/opt/webapps/hobby.war</Set>
|
||||
<Set name="virtualHosts">
|
||||
|
|
@ -143,12 +143,12 @@ This configuration may be useful when Jetty sits behind a load balancer.
|
|||
In this case, you want to xref:og-protocols[configure multiple connectors], each with a different name, and then reference the connector name in the web application virtual host configuration:
|
||||
|
||||
.domain.xml
|
||||
[source,xml,highlight=10]
|
||||
[source,xml,highlight=10,subs="verbatim,attributes"]
|
||||
----
|
||||
<?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.ee9.webapp.WebAppContext">
|
||||
<Configure class="org.eclipse.jetty.{ee-current}.webapp.WebAppContext">
|
||||
<Set name="contextPath">/</Set>
|
||||
<Set name="war">/opt/webapps/domain.war</Set>
|
||||
<Set name="virtualHosts">
|
||||
|
|
@ -160,12 +160,12 @@ In this case, you want to xref:og-protocols[configure multiple connectors], each
|
|||
----
|
||||
|
||||
.hobby.xml
|
||||
[source,xml,highlight=10]
|
||||
[source,xml,highlight=10,subs="verbatim,attributes"]
|
||||
----
|
||||
<?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.ee9.webapp.WebAppContext">
|
||||
<Configure class="org.eclipse.jetty.{ee-current}.webapp.WebAppContext">
|
||||
<Set name="contextPath">/</Set>
|
||||
<Set name="war">/opt/webapps/hobby.war</Set>
|
||||
<Set name="virtualHosts">
|
||||
|
|
|
|||
|
|
@ -0,0 +1,23 @@
|
|||
//
|
||||
// ========================================================================
|
||||
// Copyright (c) 1995 Mort Bay Consulting Pty Ltd and others.
|
||||
//
|
||||
// This program and the accompanying materials are made available under the
|
||||
// terms of the Eclipse Public License v. 2.0 which is available at
|
||||
// https://www.eclipse.org/legal/epl-2.0, or the Apache License, Version 2.0
|
||||
// which is available at https://www.apache.org/licenses/LICENSE-2.0.
|
||||
//
|
||||
// SPDX-License-Identifier: EPL-2.0 OR Apache-2.0
|
||||
// ========================================================================
|
||||
//
|
||||
|
||||
[[og-module-core-deploy]]
|
||||
===== Module `core-deploy`
|
||||
|
||||
include::{jetty-home}/modules/{ee-current}-deploy.mod[tags=description]
|
||||
|
||||
Deployment is managed via a `DeploymentManager` component that watches a directory for changes.
|
||||
See xref:og-deploy[how to deploy web applications] for more information.
|
||||
|
||||
TODO
|
||||
// TODO see module-eeN-deploy.adoc
|
||||
|
|
@ -17,6 +17,7 @@
|
|||
include::module-alpn.adoc[]
|
||||
include::module-bytebufferpool.adoc[]
|
||||
include::module-console-capture.adoc[]
|
||||
include::module-core-deploy.adoc[]
|
||||
include::module-eeN-deploy.adoc[]
|
||||
include::module-http.adoc[]
|
||||
include::module-http2.adoc[]
|
||||
|
|
|
|||
Loading…
Reference in New Issue