Jetty 12.0.x documentation (jetty#9096)

* fix broken include
* fix demo module example
* add documentation markup to fix documentation build error
* editorial suggestions for installation instructions
* editorial suggestions for quickstart guide
* fix unresolved directive errors
* fix file not found exception thrown during doc build
* editorial suggestions for deployment quickstart, plus some fixed references
* Update documentation/jetty-documentation/src/main/asciidoc/operations-guide/begin/start.adoc

Co-authored-by: Simone Bordet <[email protected]>

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, you need to enable the xref:og-module-deploy[`deploy` module]:
 
 ----
 $ java -jar $JETTY_HOME/start.jar --add-module=deploy
@@ -57,20 +57,21 @@ $ 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.
+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]
 ====
-The `deploy` module only provides the feature of deploying web applications.
+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.
 
-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 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=demo-simple
+$ java -jar $JETTY_HOME/start.jar --add-module=ee10-demo-simple
 ----
 
 The `$JETTY_BASE` directory is now:
@@ -81,9 +82,10 @@ $JETTY_BASE
 │   └── 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 +96,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].

documentation/jetty-documentation/src/main/asciidoc/operations-guide/begin/install.adoc

@@ -14,16 +14,16 @@
 [[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}`.
+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}`.
 
-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.
+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}`.
 
-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.
+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].

documentation/jetty-documentation/src/main/asciidoc/operations-guide/begin/start.adoc

@@ -14,18 +14,18 @@
 [[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, 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:
+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
@@ -36,28 +36,33 @@ $ 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 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.
 
-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):
+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].
 
 ----
 $ 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:
+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.
+
+You can now start Jetty:
 
 ----
 $ java -jar $JETTY_HOME/start.jar
@@ -68,24 +73,31 @@ $ 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.
+But 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 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]
 ----
-JETTY_BASE
+$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 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 `+*.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 you can find the following content (among other content):
+In the `http.ini` file you can find the following (among other contents):
 
 .http.ini
 [source,subs=verbatim]
@@ -96,15 +108,10 @@ 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`:
+Try changing the default port.
+Open `http.ini`, uncomment the line containing `jetty.http.port=`, and change its value to `9999`:
 
 .http.ini
 ----
@@ -113,7 +120,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 +131,16 @@ $ 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.

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:

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/ee10-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=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.
 
 ====== 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 EE10 implementation of `AuthConfigProvider` to register a `ServerAuthModule` directly.
 
 [source, xml]
 ----
-include::{JETTY_HOME}/etc/jaspi/jaspi-demo.xml[]
+include::{JETTY_HOME}/etc/jaspi/jetty-ee10-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/ee10-jaspi-default-auth-config-factory.mod[]
+----

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.