From e74ba85b61c21227b4c78543d2b3d27432e5af19 Mon Sep 17 00:00:00 2001 From: Greg Poulos Date: Mon, 26 Dec 2022 11:45:58 -0500 Subject: [PATCH 01/14] fix broken include --- .../src/main/asciidoc/operations-guide/start/chapter.adoc | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/documentation/jetty-documentation/src/main/asciidoc/operations-guide/start/chapter.adoc b/documentation/jetty-documentation/src/main/asciidoc/operations-guide/start/chapter.adoc index cb06f42b7e46..72afb8bace8c 100644 --- a/documentation/jetty-documentation/src/main/asciidoc/operations-guide/start/chapter.adoc +++ b/documentation/jetty-documentation/src/main/asciidoc/operations-guide/start/chapter.adoc @@ -69,5 +69,5 @@ This is useful for capturing startup issues where the Jetty-specific logger has ==== Usage Reference ---- -include::../../../../../../../jetty-start/src/main/resources/org/eclipse/jetty/start/usage.txt[] +include::../../../../../../../jetty-core/jetty-start/src/main/resources/org/eclipse/jetty/start/usage.txt[] ---- From 887ec8e792870dd07e8c86d6512320ece17e4e02 Mon Sep 17 00:00:00 2001 From: Greg Poulos Date: Mon, 26 Dec 2022 11:46:19 -0500 Subject: [PATCH 02/14] fix demo module example --- jetty-home/src/main/resources/README.adoc | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/jetty-home/src/main/resources/README.adoc b/jetty-home/src/main/resources/README.adoc index a2d0bfee48fc..30601e47e3bd 100644 --- a/jetty-home/src/main/resources/README.adoc +++ b/jetty-home/src/main/resources/README.adoc @@ -32,7 +32,7 @@ The last command creates a `$JETTY_BASE/start.d/` directory and other directorie To deploy Jetty's demo web applications, run this command: ---- -$ java -jar $JETTY_HOME/start.jar --add-module=demo +$ java -jar $JETTY_HOME/start.jar --add-module=demos ---- Now you can start the Jetty server with: From 75556dcf2aad739d95b3a980e34cbd1feec1b76b Mon Sep 17 00:00:00 2001 From: Greg Poulos Date: Mon, 26 Dec 2022 11:47:04 -0500 Subject: [PATCH 03/14] add documentation markup to fix documentation build error --- jetty-core/jetty-server/src/main/config/modules/requestlog.mod | 2 ++ 1 file changed, 2 insertions(+) diff --git a/jetty-core/jetty-server/src/main/config/modules/requestlog.mod b/jetty-core/jetty-server/src/main/config/modules/requestlog.mod index 44e7a6e9e141..786f90cd2983 100644 --- a/jetty-core/jetty-server/src/main/config/modules/requestlog.mod +++ b/jetty-core/jetty-server/src/main/config/modules/requestlog.mod @@ -20,6 +20,7 @@ logs/ jetty.requestlog.dir?=logs [ini-template] +# tag::documentation[] ## Format string # jetty.requestlog.formatString=%{client}a - %u %{dd/MMM/yyyy:HH:mm:ss ZZZ|GMT}t "%r" %s %O "%{Referer}i" "%{User-Agent}i" @@ -40,3 +41,4 @@ jetty.requestlog.dir?=logs ## Timezone of the log file rollover # jetty.requestlog.timezone=GMT +# end::documentation[] From ad0376dba86cc981e7140e6d9e3312d5ee6d08dc Mon Sep 17 00:00:00 2001 From: Greg Poulos Date: Mon, 26 Dec 2022 11:48:00 -0500 Subject: [PATCH 04/14] editorial suggestions for installation instructions --- .../asciidoc/operations-guide/begin/install.adoc | 12 +++++------- 1 file changed, 5 insertions(+), 7 deletions(-) diff --git a/documentation/jetty-documentation/src/main/asciidoc/operations-guide/begin/install.adoc b/documentation/jetty-documentation/src/main/asciidoc/operations-guide/begin/install.adoc index ec1788c1617a..1f1bc66a558c 100644 --- a/documentation/jetty-documentation/src/main/asciidoc/operations-guide/begin/install.adoc +++ b/documentation/jetty-documentation/src/main/asciidoc/operations-guide/begin/install.adoc @@ -14,16 +14,14 @@ [[og-begin-install]] ==== Installing Jetty -After the download, unpacking Eclipse Jetty will extract the files into a directory called `jetty-home-VERSION`, where `VERSION` is the version that you downloaded, for example `{version}`, so that the directory is called `jetty-home-{version}`. - -Unpack Eclipse Jetty compressed file in a convenient location, for example under `/opt`. - -CAUTION: For Windows users, you should unpack Jetty to a path that does not contain spaces. - -The rest of the instructions in this documentation will refer to this location as `$JETTY_HOME`, or `${jetty.home}`. +After the download, unpacking Eclipse Jetty will extract the files into a directory called `jetty-home-VERSION`, where `VERSION` is the version of Jetty that you downloaded. For example, installing Jetty {version} will create a directory called `jetty-home-{version}`. IMPORTANT: It is important that *only* stable release versions are used in production environments. Versions that have been deprecated or are released as Milestones (M), Alpha, Beta or Release Candidates (RC) are *not* suitable for production as they may contain security flaws or incomplete/non-functioning feature sets. +Unpack Eclipse Jetty file into a convenient location, such as `/opt`. The rest of the instructions in this documentation will refer to this location as `$JETTY_HOME`, or `${jetty.home}`. + +CAUTION: For Windows users, you should unpack Jetty to a path that does not contain spaces. + If you are new to Jetty, you should read the xref:og-arch[Jetty architecture section] to become familiar with the terms used in this documentation. Otherwise, you can jump to the xref:og-begin-start[section on starting Jetty]. From ae02c6cad39c1bdd3aedd5f6a2ffcb90df814e95 Mon Sep 17 00:00:00 2001 From: Greg Poulos Date: Mon, 26 Dec 2022 11:50:38 -0500 Subject: [PATCH 05/14] editorial suggestions for quickstart guide --- .../operations-guide/begin/start.adoc | 68 ++++++++++--------- 1 file changed, 36 insertions(+), 32 deletions(-) diff --git a/documentation/jetty-documentation/src/main/asciidoc/operations-guide/begin/start.adoc b/documentation/jetty-documentation/src/main/asciidoc/operations-guide/begin/start.adoc index a00c854b82fa..00cf067c11e3 100644 --- a/documentation/jetty-documentation/src/main/asciidoc/operations-guide/begin/start.adoc +++ b/documentation/jetty-documentation/src/main/asciidoc/operations-guide/begin/start.adoc @@ -14,18 +14,17 @@ [[og-begin-start]] ==== Starting Jetty -Eclipse Jetty as a standalone server has no graphical user interface, so configuring and running the server is done from the command line. +Eclipse Jetty as a standalone server has no graphical user interface; configuring and running the server is done from the command line. -Recall from the xref:og-arch[architecture section] that Jetty is based on xref:og-modules[modules], that provides features, and on xref:og-arch-jetty-base[`$JETTY_BASE`], the place where you configure which module (and therefore which feature) you want to enable, and where you configure module parameters. - -Jetty is started by executing `$JETTY_HOME/start.jar` from within a `$JETTY_BASE` directory, so first we need to create a `$JETTY_BASE`: +First we need to create a `$JETTY_BASE` directory. ---- $ JETTY_BASE=/path/to/jetty.base +$ mkdir $JETTY_BASE $ cd $JETTY_BASE ---- -If you try to start Jetty from an empty `$JETTY_BASE` you get: +We'll start Jetty by executing `$JETTY_HOME/start.jar` from this directory. However, if we try to start Jetty from an empty `$JETTY_BASE`, it will complain that we haven't enabled any modules: ---- $ java -jar $JETTY_HOME/start.jar @@ -36,28 +35,32 @@ $ java -jar $JETTY_HOME/start.jar include::jetty[] ---- -Jetty exited complaining that there are no modules enabled, since the `$JETTY_BASE` you just created is empty and therefore there is no configuration to read to assemble the Jetty server. +Jetty uses a xref:og-modules[module] system to configure and assemble its web server; these modules are enabled and configured in xref:og-arch-jetty-base[`$JETTY_BASE`]. Since the `$JETTY_BASE` directory we just created is empty, Jetty has no configuration it can use to assemble the server. -However, it shows that `start.jar` takes parameters, whose details can be found in xref:og-start[this section]. +NOTE: See the xref:og-arch[architecture section] of this document for more information on the design of Jetty's module system. -You can explore what modules are available out of the box via: +You can explore what modules are available with the `--list-modules` flag: ---- $ java -jar $JETTY_HOME/start.jar --list-modules=* ---- -Let's try to enable the `http` module (see also xref:og-protocols-http[this section] for additional information): +Let's try to enable the xref:og-protocols-http[`http`] module. + +NOTE: If you want to enable support for protocols like secure HTTP/1.1 or HTTP/2 or HTTP/3, or want to configure Jetty behind a load balancer, read xref:og-protocols[this section]. ---- $ java -jar $JETTY_HOME/start.jar --add-module=http ---- -[source,options=nowrap] +[source,subs=quotes,options=nowrap] ---- -include::jetty[args="--add-module=http"] +include::jetty[args="--add-module=http",highlight="([a-z\-]+ *transitively enabled)"] ---- -Now you can start Jetty: +Note that Jetty has enabled a number of transitive dependencies (`server`, `logging-jetty`, and so on) in order to activate the `http` module. + +Now we can start Jetty: ---- $ java -jar $JETTY_HOME/start.jar @@ -68,24 +71,27 @@ $ java -jar $JETTY_HOME/start.jar include::jetty[args="--module=http",highlight="(\{.*:8080})"] ---- -Note how Jetty is listening on port `8080` for clear-text HTTP/1.1 connections. +Jetty is listening on port `8080` for clear-text HTTP/1.1 connections. However, since it has no web applications deployed, it will just reply with `404 Not Found` to every request. -After having enabled the `http` module, the `$JETTY_BASE` directory looks like this: +Before we xref:og-begin-deploy[deploy our first web application], let's see what's happened to the `$JETTY_BASE` directory now that we've enabled the `http` module: [source,subs=verbatim] ---- -JETTY_BASE +$ tree $JETTY_BASE +/path/to/jetty.base ├── resources │ └── jetty-logging.properties <1> └── start.d <2> └── http.ini <3> ---- -<1> The `resources/jetty-logging.properties` file has been created because the `http` modules depends on the `server` module, which in turn depends on the `logging` module; the `logging` module created this file that can be configured to control the server logging level. -<2> The `start.d/` directory contains the configuration files for the modules. -<3> The `start.d/http.ini` file is the `http` module configuration file, where you can specify values for the `http` module properties. +<1> The `resources/jetty-logging.properties` file configures the server's logging level. This file was auto-generated when the `jetty-logging` module was activated as a transitive dependency of the `http` module. +<2> The `start.d/` directory contains configuration files for any modules you have explicitly activated. +<3> The `start.d/http.ini` file is the `http` module configuration file, where you can specify values for the xref:og-module-http[`http` module properties]. + +NOTE: By default, Jetty does not generate configuration files in `start.d/` for modules activated as transitive dependencies. To manually configure such a module, you should activate it directly via Jetty's `--add_module` flag. -In the `http.ini` file you can find the following content (among other content): +In the `http.ini` file we can find the following (among other contents): .http.ini [source,subs=verbatim] @@ -96,15 +102,9 @@ In the `http.ini` file you can find the following content (among other content): ---- <1> This line enables the `http` module and should not be modified. -<2> This line is commented out and specifies the default value for the module property `jetty.http.port`, which is the network port that listens for clear-text HTTP connections. +<2> This commented line specifies the default value for the `jetty.http.port` property, which is the network port that Jetty uses to listen for clear-text HTTP connections. -You can change the module property `jetty.http.port` value directly from the command line: - ----- -$ java -jar $JETTY_HOME/start.jar jetty.http.port=9999 ----- - -To make this change persistent, you can edit the `http.ini` file, uncomment the module property `jetty.http.port` and change its value to `9999`: +Let's change that default port. Open `http.ini`, uncomment the line containing `jetty.http.port=`, and change its value to `9999`: .http.ini ---- @@ -113,7 +113,7 @@ jetty.http.port=9999 ... ---- -If you restart Jetty, the new value will be used: +If you restart Jetty, it will use this new value: ---- $ java -jar $JETTY_HOME/start.jar @@ -124,11 +124,15 @@ $ java -jar $JETTY_HOME/start.jar include::jetty[args="--module=http jetty.http.port=9999",highlight="(\{.*:9999})"] ---- -Note how Jetty is now listening on port `9999` for clear-text HTTP/1.1 connections. +You can also specify the value of a module property when you start up Jetty. A property value specified on the command-line in this way will *override* the value configured in a module's `.ini` file. -NOTE: If you want to enable support for different protocols such as secure HTTP/1.1 or HTTP/2 or HTTP/3, or configure Jetty behind a load balancer, read xref:og-protocols[this section]. +---- +$ java -jar $JETTY_HOME/start.jar jetty.http.port=8080 +---- -The Jetty server is now up and running, but it has no web applications deployed, so it just replies with `404 Not Found` to every request. -It is time to xref:og-begin-deploy[deploy your web applications] to Jetty. +[source,subs=quotes,options=nowrap] +---- +include::jetty[args="--module=http jetty.http.port=8080",highlight="(\{.*:8080})"] +---- For more detailed information about the Jetty start mechanism, you can read the xref:og-arch-start[Jetty start mechanism] section. From 83ceb338a69788694eb3b230a6fea678686892ce Mon Sep 17 00:00:00 2001 From: Greg Poulos Date: Tue, 27 Dec 2022 12:42:00 -0500 Subject: [PATCH 06/14] fix unresolved directive errors --- .../operations-guide/jaas/chapter.adoc | 4 ++-- .../operations-guide/jaspi/chapter.adoc | 18 ++++++++++-------- .../asciidoc/operations-guide/jsp/chapter.adoc | 8 ++++---- 3 files changed, 16 insertions(+), 14 deletions(-) diff --git a/documentation/jetty-documentation/src/main/asciidoc/operations-guide/jaas/chapter.adoc b/documentation/jetty-documentation/src/main/asciidoc/operations-guide/jaas/chapter.adoc index f7bde4aaa8dc..0c80bb02a28b 100644 --- a/documentation/jetty-documentation/src/main/asciidoc/operations-guide/jaas/chapter.adoc +++ b/documentation/jetty-documentation/src/main/asciidoc/operations-guide/jaas/chapter.adoc @@ -36,10 +36,10 @@ own custom link:https://docs.oracle.com/javase/7/docs/api/javax/security/auth/sp [[og-jaas-module]] ===== The `jaas` module -Enable the `jaas` module: +Enable the `ee{8,9,10}-jaas` module appropriate for your EE platform: ---- -include::{JETTY_HOME}/modules/jaas.mod[] +include::{JETTY_HOME}/modules/ee10-jaas.mod[] ---- The configurable items in the resulting `$jetty.base/start.d/jaas.ini` file are: diff --git a/documentation/jetty-documentation/src/main/asciidoc/operations-guide/jaspi/chapter.adoc b/documentation/jetty-documentation/src/main/asciidoc/operations-guide/jaspi/chapter.adoc index 49111713e9dd..9a89e7d17bc4 100644 --- a/documentation/jetty-documentation/src/main/asciidoc/operations-guide/jaspi/chapter.adoc +++ b/documentation/jetty-documentation/src/main/asciidoc/operations-guide/jaspi/chapter.adoc @@ -27,29 +27,31 @@ Only modules conforming to the "Servlet Container Profile" with the ServerAuthMo Enable the `jaspi` module: ---- -include::{JETTY_HOME}/modules/jaspi.mod[] +include::{JETTY_HOME}/modules/ee9-jaspi.mod[] ---- [[og-jaspi-xml]] ===== Configure JASPI -To enable the `jaspi` module you can use the following command (issued from within the `$JETTY_BASE` directory): +Activate the `ee{9,10}-jaspi` module that matches your EE platform version. ---- -$ java -jar $JETTY_HOME/start.jar --add-modules=jaspi +$ java -jar $JETTY_HOME/start.jar --add-modules=ee9-jaspi ---- You can then register a `AuthConfigProvider` onto the static `AuthConfigFactory` obtained with `AuthConfigFactory.getFactory()`. This registration can be done in the XML configuration file which will be copied to `$JETTY_BASE/etc/jaspi/jaspi-authmoduleconfig.xml` when the module is enabled. ====== JASPI Demo -The `jaspi-demo` module illustrates setting up HTTP Basic Authentication using a Jakarta Authentication module that comes packaged with jetty: `org.eclipse.jetty.security.jaspi.modules.BasicAuthenticationAuthModule`, and applies it for a context named `/test`. +The `ee9-jaspi-demo` and `ee10-jaspi-demo` modules illustrate setting up HTTP Basic Authentication using the EE9 and EE10 Jakarta Authentication modules that come packaged with Jetty. + +The following example uses Jetty's EE9 implementation of `AuthConfigProvider` to register a `ServerAuthModule` directly. [source, xml] ---- -include::{JETTY_HOME}/etc/jaspi/jaspi-demo.xml[] +include::{JETTY_HOME}/etc/jaspi/jetty-ee9-jaspi-demo.xml[] ---- -This example uses the `AuthConfigProvider` implementation provided by Jetty to register a `ServerAuthModule` directly. Other custom or 3rd party modules that are compatible with the `ServerAuthModule` interface in JASPI can be registered in the same way. +Other custom or 3rd party modules that are compatible with the `ServerAuthModule` interface in JASPI can be registered in the same way. ===== Integration with Jetty Authentication Mechanisms @@ -61,8 +63,8 @@ The `CallerPrincipalCallback` and `GroupPrincipalCallback` do not require use of Jetty provides an implementation of the `AuthConfigFactory` interface which is used to register `AuthConfigProviders`. This can be replaced by a custom implementation by adding a custom module which provides `auth-config-factory`. This custom module must reference an XML file which sets a new instance of the `AuthConfigFactory` with the static method `AuthConfigFactory.setFactory()`. -For an example of this see the `jaspi-default-auth-config-factory` module, which provides the default implementation used by Jetty. +For an example of this see the `ee{9,10}-jaspi-default-auth-config-factory` module, which provides the default implementation used by Jetty. ---- -include::{JETTY_HOME}/modules/jaspi-default-auth-config-factory.mod[] +include::{JETTY_HOME}/modules/ee9-jaspi-default-auth-config-factory.mod[] ---- \ No newline at end of file diff --git a/documentation/jetty-documentation/src/main/asciidoc/operations-guide/jsp/chapter.adoc b/documentation/jetty-documentation/src/main/asciidoc/operations-guide/jsp/chapter.adoc index 993d39c71d52..9590ac1f3737 100644 --- a/documentation/jetty-documentation/src/main/asciidoc/operations-guide/jsp/chapter.adoc +++ b/documentation/jetty-documentation/src/main/asciidoc/operations-guide/jsp/chapter.adoc @@ -14,10 +14,10 @@ [[og-jsp]] === Java Server Pages -Jetty supports JSP via the `jsp` module, which is based on Apache Jasper: +Jetty supports JSP via the `ee{8,9,10}-jsp` modules, which are based on Apache Jasper: ---- -include::{JETTY_HOME}/modules/jsp.mod[] +include::{JETTY_HOME}/modules/ee10-jsp.mod[] ---- Logging has been bridged to Jetty logging, so you can enable logging for the `org.apache.jasper` package, subpackages and classes as usual. @@ -172,10 +172,10 @@ If the value you set doesn't take effect, try using all lower case instead of ca === JavaServer Pages Standard Tag Libraries -The JavaServer Pages Standard Tag Library (JSTL) is part of the Jetty distribution, and is available via the `jstl` module: +The JavaServer Pages Standard Tag Library (JSTL) is part of the Jetty distribution, and is available via the `ee{8,9,10}-jstl` modules: ---- -include::{JETTY_HOME}/modules/jstl.mod[] +include::{JETTY_HOME}/modules/ee10-jstl.mod[] ---- When enabled, Jetty will make the JSTL tags available for your webapps. From 09e98bb5e79bc081b1ef75f19012678b2c32ca9b Mon Sep 17 00:00:00 2001 From: Greg Poulos Date: Tue, 27 Dec 2022 12:42:40 -0500 Subject: [PATCH 07/14] fix file not found exception thrown during doc build --- .../asciidoc/operations-guide/modules/module-requestlog.adoc | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/documentation/jetty-documentation/src/main/asciidoc/operations-guide/modules/module-requestlog.adoc b/documentation/jetty-documentation/src/main/asciidoc/operations-guide/modules/module-requestlog.adoc index 5e3b44c4040d..5852ebd82f94 100644 --- a/documentation/jetty-documentation/src/main/asciidoc/operations-guide/modules/module-requestlog.adoc +++ b/documentation/jetty-documentation/src/main/asciidoc/operations-guide/modules/module-requestlog.adoc @@ -24,4 +24,4 @@ include::{JETTY_HOME}/modules/requestlog.mod[tags=documentation] The property `jetty.requestlog.formatString` can be customized using format codes. -include::javadoc[file=jetty-server/src/main/java/org/eclipse/jetty/server/CustomRequestLog.java,xsl=src/main/asciidoc/operations-guide/modules/module-requestlog.xsl,tags=documentation,replace="\|,\\|"] +include::javadoc[file=jetty-core/jetty-server/src/main/java/org/eclipse/jetty/server/CustomRequestLog.java,xsl=src/main/asciidoc/operations-guide/modules/module-requestlog.xsl,tags=documentation,replace="\|,\\|"] From a76327ab7b0f13416406dc5407ae9d5d341b2475 Mon Sep 17 00:00:00 2001 From: Greg Poulos Date: Tue, 27 Dec 2022 13:00:06 -0500 Subject: [PATCH 08/14] editorial suggestions for deployment quickstart, plus some fixed references --- .../operations-guide/begin/deploy.adoc | 37 ++++++++++--------- 1 file changed, 19 insertions(+), 18 deletions(-) diff --git a/documentation/jetty-documentation/src/main/asciidoc/operations-guide/begin/deploy.adoc b/documentation/jetty-documentation/src/main/asciidoc/operations-guide/begin/deploy.adoc index ed20e96c220c..7caa2b77c1c1 100644 --- a/documentation/jetty-documentation/src/main/asciidoc/operations-guide/begin/deploy.adoc +++ b/documentation/jetty-documentation/src/main/asciidoc/operations-guide/begin/deploy.adoc @@ -14,11 +14,11 @@ [[og-begin-deploy]] ==== Deploying Web Applications -For the purpose of deploying web applications to Jetty, there are two types of resources that can be deployed: +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 Servlet specification. +* *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 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]. [[og-begin-deploy-war]] @@ -41,12 +41,12 @@ mywebapp.war ---- <1> Publicly accessible resources such as `+*.html+`, `+*.jsp+`, `+*.css+`, `+*.js+` files, etc. are placed in `+*.war+` or in sub-directories of the `+*.war+`. <2> `WEB-INF` is a special directory used to store anything related to the web application that must not be publicly accessible, but may be accessed by other resources. -<3> `WEB-INF/classes` stores the web application compiled `+*.class+` files -<4> `WEB-INF/classes` stores the web application `+*.jar+` files -<5> `WEB-INF/web.xml` is the web application deployment descriptor defines the components and the configuration of your web application. +<3> `WEB-INF/classes` stores the web application's compiled `+*.class+` files +<4> `WEB-INF/classes` stores the web application's `+*.jar+` files +<5> `WEB-INF/web.xml` is the web application deployment descriptor, which defines the components and the configuration of your web application. ==== -To deploy a standard web application, you need to enable the `deploy` module (see the `deploy` module complete definition xref:og-module-deploy[here]). +To deploy a standard web application, we'll need to enable the xref:og-module-deploy[`deploy` module]: ---- $ java -jar $JETTY_HOME/start.jar --add-module=deploy @@ -57,33 +57,34 @@ $ java -jar $JETTY_HOME/start.jar --add-module=deploy include::jetty[setupArgs="--add-module=http",args="--add-module=deploy"] ---- -The `deploy` module creates the `$JETTY_BASE/webapps` directory, the directory where `+*.war+` files or web application directories should be copied so that Jetty can deploy them. +Activating the `deploy` module will create the `$JETTY_BASE/webapps` directory, which is where Jetty will look for any `+*.war+` files or web application directories to deploy. [NOTE] ==== -The `deploy` module only provides the feature of deploying web applications. +Activating Jetty's `deploy` module only enables web application deployment. Whether these web applications are served via clear-text HTTP/1.1, or secure HTTP/1.1, or secure HTTP/2, or HTTP/3 (or even all of these protocols) depends on whether the correspondent Jetty modules have been enabled. -Whether these web applications are served via clear-text HTTP/1.1, or secure HTTP/1.1, or secure HTTP/2, or HTTP/3 (or even all of these protocols) depends on whether the correspondent Jetty modules have been enabled. Refer to the xref:og-protocols[section about protocols] for further information. ==== -Now you need to copy a web application to the `$JETTY_BASE/webapps` directory, and you can use one of the demos shipped with Jetty: +Now let's copy a web application to the `$JETTY_BASE/webapps` directory. We can use one of the demos shipped with Jetty: ---- -$ java -jar $JETTY_HOME/start.jar --add-module=demo-simple +$ java -jar $JETTY_HOME/start.jar --add-module=ee10-demo-simple ---- The `$JETTY_BASE` directory is now: ---- -$JETTY_BASE +$ tree $JETTY_BASE +/path/to/jetty.base ├── resources │ └── jetty-logging.properties ├── start.d │ ├── deploy.ini +│ ├── ee10-demo-simple.ini │ └── http.ini └── webapps - └── demo-simple.war + └── ee10-demo-simple.war ---- Now start Jetty: @@ -94,14 +95,14 @@ $ java -jar $JETTY_HOME/start.jar [source,subs=quotes,options=nowrap] ---- -include::jetty[setupArgs="--add-modules=http,deploy,demo-simple",highlight="WebAppContext"] +include::jetty[setupArgs="--add-modules=http,deploy,ee10-demo-simple",highlight="WebAppContext"] ---- -Note the highlighted line that logs the deployment of `demo-simple.war`. +Note the highlighted line that logs the deployment of `ee10-demo-simple.war`. -Now you can access the web application by pointing your browser to `+http://localhost:8080/demo-simple+`. +Now you can access the web application by pointing your browser to `+http://localhost:8080/ee10-demo-simple+`. [[og-begin-deploy-war-advanced]] ===== Advanced Deployment -If you want to customize the deployment of your web application, for example by specifying a `contextPath` different from the file/directory name, or by specifying JNDI entries, or by specifying virtual hosts, etc. read xref:og-deploy[this section]. +If you want to customize the deployment of your web application -- for example, by specifying a `contextPath` different from the file/directory name, or by specifying JNDI entries, or by specifying virtual hosts -- read xref:og-deploy[this section]. From 5221555966c611249b5916f88fd8a8134ae9aa02 Mon Sep 17 00:00:00 2001 From: Greg Poulos Date: Tue, 3 Jan 2023 15:23:34 -0800 Subject: [PATCH 09/14] Update documentation/jetty-documentation/src/main/asciidoc/operations-guide/begin/start.adoc Co-authored-by: Simone Bordet --- .../src/main/asciidoc/operations-guide/begin/start.adoc | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/documentation/jetty-documentation/src/main/asciidoc/operations-guide/begin/start.adoc b/documentation/jetty-documentation/src/main/asciidoc/operations-guide/begin/start.adoc index 00cf067c11e3..c06993cc70ef 100644 --- a/documentation/jetty-documentation/src/main/asciidoc/operations-guide/begin/start.adoc +++ b/documentation/jetty-documentation/src/main/asciidoc/operations-guide/begin/start.adoc @@ -35,7 +35,8 @@ $ java -jar $JETTY_HOME/start.jar include::jetty[] ---- -Jetty uses a xref:og-modules[module] system to configure and assemble its web server; these modules are enabled and configured in xref:og-arch-jetty-base[`$JETTY_BASE`]. Since the `$JETTY_BASE` directory we just created is empty, Jetty has no configuration it can use to assemble the server. +Jetty uses a xref:og-modules[module system] to configure and assemble the server; these modules are enabled and configured in xref:og-arch-jetty-base[`$JETTY_BASE`]. +Since the `$JETTY_BASE` directory you just created is empty, Jetty has no configuration it can use to assemble the server. NOTE: See the xref:og-arch[architecture section] of this document for more information on the design of Jetty's module system. From 31759fb7c50f5ff53795f22e9002d83d3c7987b7 Mon Sep 17 00:00:00 2001 From: Greg Poulos Date: Tue, 3 Jan 2023 15:27:19 -0800 Subject: [PATCH 10/14] Update documentation/jetty-documentation/src/main/asciidoc/operations-guide/begin/start.adoc Co-authored-by: Simone Bordet --- .../src/main/asciidoc/operations-guide/begin/start.adoc | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/documentation/jetty-documentation/src/main/asciidoc/operations-guide/begin/start.adoc b/documentation/jetty-documentation/src/main/asciidoc/operations-guide/begin/start.adoc index c06993cc70ef..91a2ffd9fc89 100644 --- a/documentation/jetty-documentation/src/main/asciidoc/operations-guide/begin/start.adoc +++ b/documentation/jetty-documentation/src/main/asciidoc/operations-guide/begin/start.adoc @@ -59,7 +59,7 @@ $ java -jar $JETTY_HOME/start.jar --add-module=http include::jetty[args="--add-module=http",highlight="([a-z\-]+ *transitively enabled)"] ---- -Note that Jetty has enabled a number of transitive dependencies (`server`, `logging-jetty`, and so on) in order to activate the `http` module. +When Jetty enables the `http` module, it also automatically enables a number of transitive dependencies of the `http` module, such as the `server` module, the `logging-jetty` module, and so on. Now we can start Jetty: From a2bb35296a6cfc38a636094bf66b0e230fd6c52b Mon Sep 17 00:00:00 2001 From: Greg Poulos Date: Tue, 3 Jan 2023 15:31:56 -0800 Subject: [PATCH 11/14] Update documentation/jetty-documentation/src/main/asciidoc/operations-guide/begin/start.adoc Co-authored-by: Simone Bordet --- .../src/main/asciidoc/operations-guide/begin/start.adoc | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/documentation/jetty-documentation/src/main/asciidoc/operations-guide/begin/start.adoc b/documentation/jetty-documentation/src/main/asciidoc/operations-guide/begin/start.adoc index 91a2ffd9fc89..9adf6703130b 100644 --- a/documentation/jetty-documentation/src/main/asciidoc/operations-guide/begin/start.adoc +++ b/documentation/jetty-documentation/src/main/asciidoc/operations-guide/begin/start.adoc @@ -87,7 +87,7 @@ $ tree $JETTY_BASE ---- <1> The `resources/jetty-logging.properties` file configures the server's logging level. This file was auto-generated when the `jetty-logging` module was activated as a transitive dependency of the `http` module. -<2> The `start.d/` directory contains configuration files for any modules you have explicitly activated. +<2> The `start.d/` directory contains the `+*.ini+` configuration files for any modules you have explicitly activated. <3> The `start.d/http.ini` file is the `http` module configuration file, where you can specify values for the xref:og-module-http[`http` module properties]. NOTE: By default, Jetty does not generate configuration files in `start.d/` for modules activated as transitive dependencies. To manually configure such a module, you should activate it directly via Jetty's `--add_module` flag. From f345d08f968ea4f8016c23223476c63313ace941 Mon Sep 17 00:00:00 2001 From: Greg Poulos Date: Tue, 3 Jan 2023 15:32:19 -0800 Subject: [PATCH 12/14] Update documentation/jetty-documentation/src/main/asciidoc/operations-guide/begin/start.adoc Co-authored-by: Simone Bordet --- .../src/main/asciidoc/operations-guide/begin/start.adoc | 6 +++++- 1 file changed, 5 insertions(+), 1 deletion(-) diff --git a/documentation/jetty-documentation/src/main/asciidoc/operations-guide/begin/start.adoc b/documentation/jetty-documentation/src/main/asciidoc/operations-guide/begin/start.adoc index 9adf6703130b..d1621076569f 100644 --- a/documentation/jetty-documentation/src/main/asciidoc/operations-guide/begin/start.adoc +++ b/documentation/jetty-documentation/src/main/asciidoc/operations-guide/begin/start.adoc @@ -90,7 +90,11 @@ $ tree $JETTY_BASE <2> The `start.d/` directory contains the `+*.ini+` configuration files for any modules you have explicitly activated. <3> The `start.d/http.ini` file is the `http` module configuration file, where you can specify values for the xref:og-module-http[`http` module properties]. -NOTE: By default, Jetty does not generate configuration files in `start.d/` for modules activated as transitive dependencies. To manually configure such a module, you should activate it directly via Jetty's `--add_module` flag. +[NOTE] +==== +By default, Jetty does not generate `+*.ini+` configuration files in `start.d/` for modules activated as transitive dependencies. +To manually configure such modules, you should activate them directly via Jetty's `--add-modules` flag. +==== In the `http.ini` file we can find the following (among other contents): From 3dcac293cc3d22d5bf414fda95a62ae36b711f41 Mon Sep 17 00:00:00 2001 From: Greg Poulos Date: Tue, 3 Jan 2023 15:35:24 -0800 Subject: [PATCH 13/14] Incorporate suggestions from sbordet --- .../operations-guide/begin/deploy.adoc | 13 ++++---- .../operations-guide/begin/install.adoc | 6 ++-- .../operations-guide/begin/start.adoc | 30 +++++++++++-------- .../operations-guide/jaspi/chapter.adoc | 10 +++---- 4 files changed, 33 insertions(+), 26 deletions(-) diff --git a/documentation/jetty-documentation/src/main/asciidoc/operations-guide/begin/deploy.adoc b/documentation/jetty-documentation/src/main/asciidoc/operations-guide/begin/deploy.adoc index 7caa2b77c1c1..8df0613cfa7d 100644 --- a/documentation/jetty-documentation/src/main/asciidoc/operations-guide/begin/deploy.adoc +++ b/documentation/jetty-documentation/src/main/asciidoc/operations-guide/begin/deploy.adoc @@ -46,7 +46,7 @@ mywebapp.war <5> `WEB-INF/web.xml` is the web application deployment descriptor, which defines the components and the configuration of your web application. ==== -To deploy a standard web application, we'll need to enable the xref:og-module-deploy[`deploy` module]: +To deploy a standard web application, you need to enable the xref:og-module-deploy[`deploy` module]: ---- $ java -jar $JETTY_HOME/start.jar --add-module=deploy @@ -57,16 +57,18 @@ $ java -jar $JETTY_HOME/start.jar --add-module=deploy include::jetty[setupArgs="--add-module=http",args="--add-module=deploy"] ---- -Activating the `deploy` module will create the `$JETTY_BASE/webapps` directory, which is where Jetty will look for any `+*.war+` files or web application directories to deploy. +The `deploy` module creates `$JETTY_BASE/webapps`, which is the directory where Jetty looks for any `+*.war+` files or web application directories to deploy. [NOTE] ==== -Activating Jetty's `deploy` module only enables web application deployment. Whether these web applications are served via clear-text HTTP/1.1, or secure HTTP/1.1, or secure HTTP/2, or HTTP/3 (or even all of these protocols) depends on whether the correspondent Jetty modules have been enabled. +Activating Jetty's `deploy` module enables web application deployment. +Whether these web applications are served via clear-text HTTP/1.1, or secure HTTP/1.1, or secure HTTP/2, or HTTP/3 (or even all of these protocols) depends on if the correspondent Jetty modules have been enabled. Refer to the xref:og-protocols[section about protocols] for further information. ==== -Now let's copy a web application to the `$JETTY_BASE/webapps` directory. We can use one of the demos shipped with Jetty: +Now you're ready to copy a web application to the `$JETTY_BASE/webapps` directory. +You can use one of the demos shipped with Jetty: ---- $ java -jar $JETTY_HOME/start.jar --add-module=ee10-demo-simple @@ -75,8 +77,7 @@ $ java -jar $JETTY_HOME/start.jar --add-module=ee10-demo-simple The `$JETTY_BASE` directory is now: ---- -$ tree $JETTY_BASE -/path/to/jetty.base +$JETTY_BASE ├── resources │ └── jetty-logging.properties ├── start.d diff --git a/documentation/jetty-documentation/src/main/asciidoc/operations-guide/begin/install.adoc b/documentation/jetty-documentation/src/main/asciidoc/operations-guide/begin/install.adoc index 1f1bc66a558c..68fb5bd5227c 100644 --- a/documentation/jetty-documentation/src/main/asciidoc/operations-guide/begin/install.adoc +++ b/documentation/jetty-documentation/src/main/asciidoc/operations-guide/begin/install.adoc @@ -14,12 +14,14 @@ [[og-begin-install]] ==== Installing Jetty -After the download, unpacking Eclipse Jetty will extract the files into a directory called `jetty-home-VERSION`, where `VERSION` is the version of Jetty that you downloaded. For example, installing Jetty {version} will create a directory called `jetty-home-{version}`. +After the download, unpacking Eclipse Jetty will extract the files into a directory called `jetty-home-VERSION`, where `VERSION` is the version of Jetty that you downloaded. +For example, installing Jetty {version} will create a directory called `jetty-home-{version}`. IMPORTANT: It is important that *only* stable release versions are used in production environments. Versions that have been deprecated or are released as Milestones (M), Alpha, Beta or Release Candidates (RC) are *not* suitable for production as they may contain security flaws or incomplete/non-functioning feature sets. -Unpack Eclipse Jetty file into a convenient location, such as `/opt`. The rest of the instructions in this documentation will refer to this location as `$JETTY_HOME`, or `${jetty.home}`. +Unpack Eclipse Jetty file into a convenient location, such as `/opt`. +The rest of the instructions in this documentation will refer to this location as `$JETTY_HOME`, or `${jetty.home}`. CAUTION: For Windows users, you should unpack Jetty to a path that does not contain spaces. diff --git a/documentation/jetty-documentation/src/main/asciidoc/operations-guide/begin/start.adoc b/documentation/jetty-documentation/src/main/asciidoc/operations-guide/begin/start.adoc index 00cf067c11e3..96ed3d6dc6cb 100644 --- a/documentation/jetty-documentation/src/main/asciidoc/operations-guide/begin/start.adoc +++ b/documentation/jetty-documentation/src/main/asciidoc/operations-guide/begin/start.adoc @@ -16,7 +16,7 @@ Eclipse Jetty as a standalone server has no graphical user interface; configuring and running the server is done from the command line. -First we need to create a `$JETTY_BASE` directory. +First, create a `$JETTY_BASE` directory. ---- $ JETTY_BASE=/path/to/jetty.base @@ -24,7 +24,8 @@ $ mkdir $JETTY_BASE $ cd $JETTY_BASE ---- -We'll start Jetty by executing `$JETTY_HOME/start.jar` from this directory. However, if we try to start Jetty from an empty `$JETTY_BASE`, it will complain that we haven't enabled any modules: +You will typically start Jetty by executing `$JETTY_HOME/start.jar` from this directory. +However, if you try to start Jetty from an empty `$JETTY_BASE`, it will complain that you haven't enabled any modules: ---- $ java -jar $JETTY_HOME/start.jar @@ -35,7 +36,8 @@ $ java -jar $JETTY_HOME/start.jar include::jetty[] ---- -Jetty uses a xref:og-modules[module] system to configure and assemble its web server; these modules are enabled and configured in xref:og-arch-jetty-base[`$JETTY_BASE`]. Since the `$JETTY_BASE` directory we just created is empty, Jetty has no configuration it can use to assemble the server. +Jetty uses a xref:og-modules[module] system to configure and assemble the server; these modules are enabled and configured in xref:og-arch-jetty-base[`$JETTY_BASE`]. +Since the `$JETTY_BASE` directory we just created is empty, Jetty has no configuration it can use to assemble the server. NOTE: See the xref:og-arch[architecture section] of this document for more information on the design of Jetty's module system. @@ -45,7 +47,7 @@ You can explore what modules are available with the `--list-modules` flag: $ java -jar $JETTY_HOME/start.jar --list-modules=* ---- -Let's try to enable the xref:og-protocols-http[`http`] module. +Now try to enable the xref:og-protocols-http[`http`] module. NOTE: If you want to enable support for protocols like secure HTTP/1.1 or HTTP/2 or HTTP/3, or want to configure Jetty behind a load balancer, read xref:og-protocols[this section]. @@ -60,7 +62,7 @@ include::jetty[args="--add-module=http",highlight="([a-z\-]+ *transitively enabl Note that Jetty has enabled a number of transitive dependencies (`server`, `logging-jetty`, and so on) in order to activate the `http` module. -Now we can start Jetty: +You can now start Jetty: ---- $ java -jar $JETTY_HOME/start.jar @@ -71,27 +73,27 @@ $ java -jar $JETTY_HOME/start.jar include::jetty[args="--module=http",highlight="(\{.*:8080})"] ---- -Jetty is listening on port `8080` for clear-text HTTP/1.1 connections. However, since it has no web applications deployed, it will just reply with `404 Not Found` to every request. +Jetty is listening on port `8080` for clear-text HTTP/1.1 connections. +But since it has no web applications deployed, it will just reply with `404 Not Found` to every request. -Before we xref:og-begin-deploy[deploy our first web application], let's see what's happened to the `$JETTY_BASE` directory now that we've enabled the `http` module: +Before you xref:og-begin-deploy[deploy your first web application], take a moment to see what happened to the `$JETTY_BASE` directory once you enabled the `http` module: [source,subs=verbatim] ---- -$ tree $JETTY_BASE -/path/to/jetty.base +$JETTY_BASE ├── resources │ └── jetty-logging.properties <1> └── start.d <2> └── http.ini <3> ---- -<1> The `resources/jetty-logging.properties` file configures the server's logging level. This file was auto-generated when the `jetty-logging` module was activated as a transitive dependency of the `http` module. +<1> The `resources/jetty-logging.properties` file configures the server's logging level; this file was auto-generated when the `jetty-logging` module was activated as a transitive dependency of the `http` module. <2> The `start.d/` directory contains configuration files for any modules you have explicitly activated. <3> The `start.d/http.ini` file is the `http` module configuration file, where you can specify values for the xref:og-module-http[`http` module properties]. NOTE: By default, Jetty does not generate configuration files in `start.d/` for modules activated as transitive dependencies. To manually configure such a module, you should activate it directly via Jetty's `--add_module` flag. -In the `http.ini` file we can find the following (among other contents): +In the `http.ini` file you can find the following (among other contents): .http.ini [source,subs=verbatim] @@ -104,7 +106,8 @@ In the `http.ini` file we can find the following (among other contents): <1> This line enables the `http` module and should not be modified. <2> This commented line specifies the default value for the `jetty.http.port` property, which is the network port that Jetty uses to listen for clear-text HTTP connections. -Let's change that default port. Open `http.ini`, uncomment the line containing `jetty.http.port=`, and change its value to `9999`: +Try changing the default port. +Open `http.ini`, uncomment the line containing `jetty.http.port=`, and change its value to `9999`: .http.ini ---- @@ -124,7 +127,8 @@ $ java -jar $JETTY_HOME/start.jar include::jetty[args="--module=http jetty.http.port=9999",highlight="(\{.*:9999})"] ---- -You can also specify the value of a module property when you start up Jetty. A property value specified on the command-line in this way will *override* the value configured in a module's `.ini` file. +You can also specify the value of a module property when you start up Jetty. +A property value specified on the command-line in this way will *override* the value configured in a module's `+*.ini+` file. ---- $ java -jar $JETTY_HOME/start.jar jetty.http.port=8080 diff --git a/documentation/jetty-documentation/src/main/asciidoc/operations-guide/jaspi/chapter.adoc b/documentation/jetty-documentation/src/main/asciidoc/operations-guide/jaspi/chapter.adoc index 9a89e7d17bc4..385805b57b4c 100644 --- a/documentation/jetty-documentation/src/main/asciidoc/operations-guide/jaspi/chapter.adoc +++ b/documentation/jetty-documentation/src/main/asciidoc/operations-guide/jaspi/chapter.adoc @@ -27,7 +27,7 @@ Only modules conforming to the "Servlet Container Profile" with the ServerAuthMo Enable the `jaspi` module: ---- -include::{JETTY_HOME}/modules/ee9-jaspi.mod[] +include::{JETTY_HOME}/modules/ee10-jaspi.mod[] ---- [[og-jaspi-xml]] @@ -36,7 +36,7 @@ include::{JETTY_HOME}/modules/ee9-jaspi.mod[] Activate the `ee{9,10}-jaspi` module that matches your EE platform version. ---- -$ java -jar $JETTY_HOME/start.jar --add-modules=ee9-jaspi +$ java -jar $JETTY_HOME/start.jar --add-modules=ee10-jaspi ---- You can then register a `AuthConfigProvider` onto the static `AuthConfigFactory` obtained with `AuthConfigFactory.getFactory()`. This registration can be done in the XML configuration file which will be copied to `$JETTY_BASE/etc/jaspi/jaspi-authmoduleconfig.xml` when the module is enabled. @@ -44,11 +44,11 @@ You can then register a `AuthConfigProvider` onto the static `AuthConfigFactory` ====== JASPI Demo The `ee9-jaspi-demo` and `ee10-jaspi-demo` modules illustrate setting up HTTP Basic Authentication using the EE9 and EE10 Jakarta Authentication modules that come packaged with Jetty. -The following example uses Jetty's EE9 implementation of `AuthConfigProvider` to register a `ServerAuthModule` directly. +The following example uses Jetty's EE10 implementation of `AuthConfigProvider` to register a `ServerAuthModule` directly. [source, xml] ---- -include::{JETTY_HOME}/etc/jaspi/jetty-ee9-jaspi-demo.xml[] +include::{JETTY_HOME}/etc/jaspi/jetty-ee10-jaspi-demo.xml[] ---- Other custom or 3rd party modules that are compatible with the `ServerAuthModule` interface in JASPI can be registered in the same way. @@ -67,4 +67,4 @@ For an example of this see the `ee{9,10}-jaspi-default-auth-config-factory` modu ---- include::{JETTY_HOME}/modules/ee9-jaspi-default-auth-config-factory.mod[] ----- \ No newline at end of file +---- From ea7351236ce454dd03de6ef9a2a208df2322dbd8 Mon Sep 17 00:00:00 2001 From: Greg Poulos Date: Thu, 5 Jan 2023 16:43:00 -0800 Subject: [PATCH 14/14] Use EE10 instead of EE9 in documentation examples --- .../src/main/asciidoc/operations-guide/jaspi/chapter.adoc | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/documentation/jetty-documentation/src/main/asciidoc/operations-guide/jaspi/chapter.adoc b/documentation/jetty-documentation/src/main/asciidoc/operations-guide/jaspi/chapter.adoc index 385805b57b4c..63141006bde7 100644 --- a/documentation/jetty-documentation/src/main/asciidoc/operations-guide/jaspi/chapter.adoc +++ b/documentation/jetty-documentation/src/main/asciidoc/operations-guide/jaspi/chapter.adoc @@ -66,5 +66,5 @@ This custom module must reference an XML file which sets a new instance of the ` For an example of this see the `ee{9,10}-jaspi-default-auth-config-factory` module, which provides the default implementation used by Jetty. ---- -include::{JETTY_HOME}/modules/ee9-jaspi-default-auth-config-factory.mod[] +include::{JETTY_HOME}/modules/ee10-jaspi-default-auth-config-factory.mod[] ----