diff --git a/examples/embedded/src/main/resources/jetty-otherserver.xml b/examples/embedded/src/main/resources/jetty-otherserver.xml
deleted file mode 100644
index 2a4c4d361c4..00000000000
--- a/examples/embedded/src/main/resources/jetty-otherserver.xml
+++ /dev/null
@@ -1,51 +0,0 @@
-
-
-
-
-
-
-
-
- -
-
-
- -
-
-
-
-
-
-
-
-
-
-
- - mywebapp.com
+ - www.mywebapp.com
+ - mywebapp.net
+ - www.mywebapp.net
+
+
+
+----
+
+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+`
+
+[NOTE]
+====
+You configured the `contextPath` of your web application 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.
+====
+
+[[og-deploy-virtual-hosts-same-context]]
+===== 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 webapps, while specifying different virtual hosts for each of your webapps:
+
+.domain.xml
+[source,xml]
+----
+
+
+
+
+ /
+ /opt/webapps/domain.war
+
+
+ - domain.biz
+
+
+
+----
+
+.hobby.xml
+[source,xml]
+----
+
+
+
+
+ /
+ /opt/webapps/hobby.war
+
+
+ - hobby.net
+
+
+
+----
+
+[[og-deploy-virtual-hosts-port]]
+===== Different Port, Different Web Application
+
+Sometimes it is required to serve different web applications from different IP ports, and therefore from different ``ServerConnector``s.
+
+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 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]
+----
+
+
+
+
+ /
+ /opt/webapps/domain.war
+
+
+ - @port8080
+
+
+
+----
+
+.hobby.xml
+[source,xml,highlight=10]
+----
+
+
+
+
+ /
+ /opt/webapps/hobby.war
+
+
+ - @port9090
+
+
+
+----
+
+[NOTE]
+====
+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 xref:og-protocols[this section] for further information about how to configure connectors.
+====
diff --git a/jetty-documentation/src/main/asciidoc/operations-guide/index.adoc b/jetty-documentation/src/main/asciidoc/operations-guide/index.adoc
index aaa6b04376b..70f61e182aa 100644
--- a/jetty-documentation/src/main/asciidoc/operations-guide/index.adoc
+++ b/jetty-documentation/src/main/asciidoc/operations-guide/index.adoc
@@ -17,48 +17,19 @@
//
:doctitle: Eclipse Jetty: Operations Guide
-:author: Jetty Developers
-:email: jetty-dev@eclipse.org
-:revnumber: {version}
-:revdate: {TIMESTAMP}
-:toc: left
:toc-title: Operations Guide
-:toc-style:
-
-:header-style: eclipse-thin
-:breadcrumb-style: eclipse-thin
-:footer-style: default
-
:breadcrumb: Home:../index.html | Operations Guide:./index.html
+:idprefix: og-
-// docinfo lets you pull in shared content and/or influence via render type
-//:docinfodir: {DOCINFODIR}/documentation
-//:docinfo1:
-
-// html specific directives
-ifdef::backend-html5[]
-:safe-mode-unsafe:
-:stylesdir: ../common/css
-:stylesheet: jetty.css
-:linkcss:
-:scriptsdir: ../common/js
-endif::[]
-
-// options for special blocks, code snippets, screen, etc
-:sub-order: attributes+
-
-// uncomment to allow include::https:// style content inclusion
-//:allow-uri-read: true
-
-// use fonts for admonitions
-:icons: font
-
-// suppress automatic id generation
-:sectids!:
-
-// download and install
+include::../config.adoc[]
+include::.asciidoctorconfig[]
include::introduction.adoc[]
-// TODO: jetty.home vs jetty.base
+include::begin/chapter.adoc[]
+
+include::start/chapter.adoc[]
+include::deploy/chapter.adoc[]
+include::protocols/chapter.adoc[]
+include::modules/chapter.adoc[]
// TODO: how jetty standalone work what start.jar does, command line options, modules, etc.
// TODO: this is mostly in old_docs/startup.
diff --git a/jetty-documentation/src/main/asciidoc/operations-guide/introduction.adoc b/jetty-documentation/src/main/asciidoc/operations-guide/introduction.adoc
index 8b24c06414a..0ec193ccec3 100644
--- a/jetty-documentation/src/main/asciidoc/operations-guide/introduction.adoc
+++ b/jetty-documentation/src/main/asciidoc/operations-guide/introduction.adoc
@@ -16,33 +16,31 @@
// ========================================================================
//
-[[og-guide]]
+[[og-intro]]
== Eclipse Jetty Operations Guide
The Eclipse Jetty Operations Guide targets sysops, devops, and developers who want to install Eclipse Jetty as a standalone server to deploy web applications.
-[[og-download]]
-=== Downloading Eclipse Jetty
+=== Eclipse Jetty Introduction
-The Eclipse Jetty distribution is available for download from link:https://www.eclipse.org/jetty/download.html[]
+If you are new to Eclipse Jetty, read xref:og-begin[here] to download, install, start and deploy web applications to Jetty.
-The Eclipse Jetty distribution is available in both `zip` and `gzip` formats; download the one most appropriate for your system, typically `zip` for Windows and `gzip` for other operative systems.
+=== Eclipse Jetty Features
-[[og-install]]
-=== Installing Eclipse Jetty
+If you know Jetty already, jump to a feature:
-After the download, unpacking the Eclipse Jetty distribution will extract the files into a directory called `jetty-distribution-VERSION`, where `VERSION` is the version that you downloaded, for example `10.0.0`, so that the directory is called `jetty-distribution-10.0.0`.
+TODO
-Unpack the Eclipse Jetty distribution compressed file in a convenient location, for example under `/opt`.
+* Jetty Overview
+* Jetty Modules
+* Rewrite Modules
-The rest of the instructions in this documentation will refer to this location as `$JETTY_HOME`.
+=== Eclipse Jetty How-Tos
-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.
+* xref:og-protocols-http[Configure Clear-Text HTTP/1.1]
+* xref:og-protocols-https[Configure Secure HTTP/1.1 (https)]
-[[og-running]]
-=== Running Eclipse Jetty
+TODO
-Eclipse Jetty as a standalone server has no graphical user interface, so configuring and running the server is done from the command line.
-
-TODO: section about general architecture - modules etc.
+* Jetty Behind a Load Balancer
+** Forward Header Customizer
diff --git a/jetty-documentation/src/main/asciidoc/operations-guide/modules/chapter.adoc b/jetty-documentation/src/main/asciidoc/operations-guide/modules/chapter.adoc
new file mode 100644
index 00000000000..fd9c0f22736
--- /dev/null
+++ b/jetty-documentation/src/main/asciidoc/operations-guide/modules/chapter.adoc
@@ -0,0 +1,24 @@
+//
+// ========================================================================
+// Copyright (c) 1995-2020 Mort Bay Consulting Pty Ltd and others.
+//
+// This program and the accompanying materials are made available under
+// the terms of the Eclipse Public License 2.0 which is available at
+// https://www.eclipse.org/legal/epl-2.0
+//
+// This Source Code may also be made available under the following
+// Secondary Licenses when the conditions for such availability set
+// forth in the Eclipse Public License, v. 2.0 are satisfied:
+// the Apache License v2.0 which is available at
+// https://www.apache.org/licenses/LICENSE-2.0
+//
+// SPDX-License-Identifier: EPL-2.0 OR Apache-2.0
+// ========================================================================
+//
+
+include::modules.adoc[]
+include::module-bytebufferpool.adoc[]
+include::module-deploy.adoc[]
+include::module-http.adoc[]
+include::module-server.adoc[]
+include::module-threadpool.adoc[]
diff --git a/jetty-documentation/src/main/asciidoc/operations-guide/modules/module-bytebufferpool.adoc b/jetty-documentation/src/main/asciidoc/operations-guide/modules/module-bytebufferpool.adoc
new file mode 100644
index 00000000000..2a6a1848c8b
--- /dev/null
+++ b/jetty-documentation/src/main/asciidoc/operations-guide/modules/module-bytebufferpool.adoc
@@ -0,0 +1,34 @@
+//
+// ========================================================================
+// Copyright (c) 1995-2020 Mort Bay Consulting Pty Ltd and others.
+//
+// This program and the accompanying materials are made available under
+// the terms of the Eclipse Public License 2.0 which is available at
+// https://www.eclipse.org/legal/epl-2.0
+//
+// This Source Code may also be made available under the following
+// Secondary Licenses when the conditions for such availability set
+// forth in the Eclipse Public License, v. 2.0 are satisfied:
+// the Apache License v2.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-bytebufferpool]]
+==== Module `bytebufferpool`
+
+The `bytebufferpool` module allows you to configure the server-wide `ByteBuffer` pool.
+
+// TODO: expand
+
+The module file is `$JETTY_HOME/modules/bytebufferpool.mod`:
+
+----
+include::{JETTY_HOME}/modules/bytebufferpool.mod[]
+----
+
+Among the configurable properties, the most relevant are:
+
+TODO
diff --git a/jetty-documentation/src/main/asciidoc/operations-guide/modules/module-deploy.adoc b/jetty-documentation/src/main/asciidoc/operations-guide/modules/module-deploy.adoc
new file mode 100644
index 00000000000..e913b54674b
--- /dev/null
+++ b/jetty-documentation/src/main/asciidoc/operations-guide/modules/module-deploy.adoc
@@ -0,0 +1,36 @@
+//
+// ========================================================================
+// Copyright (c) 1995-2020 Mort Bay Consulting Pty Ltd and others.
+//
+// This program and the accompanying materials are made available under
+// the terms of the Eclipse Public License 2.0 which is available at
+// https://www.eclipse.org/legal/epl-2.0
+//
+// This Source Code may also be made available under the following
+// Secondary Licenses when the conditions for such availability set
+// forth in the Eclipse Public License, v. 2.0 are satisfied:
+// the Apache License v2.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-deploy]]
+==== Module `deploy`
+
+The `deploy` module provides the deployment feature through a `DeploymentManager` component that watches a directory for changes (see xref:og-deploy[how to deploy web applications] for more information).
+
+Files or directories added in this monitored directory cause the `DeploymentManager` to deploy them as web applications; updating files already existing in this monitored directory cause the `DeploymentManager` to re-deploy the correspondent web application; removing files in this monitored directory cause the `DeploymentManager` to undeploy the correspondent web application (see also xref:og-deploy-rules[here] for more information).
+
+The module file is `$JETTY_HOME/modules/deploy.mod`:
+
+----
+include::{JETTY_HOME}/modules/deploy.mod[]
+----
+
+Among the configurable properties, the most relevant are:
+
+* `jetty.deploy.monitoredDir`, to change the name of the monitored directory.
+* `jetty.deploy.scanInterval`, to change the scan period, that is how frequently the `DeploymentManager` wakes up to scan the monitored directory for changes.
+Setting `jetty.deploy.scanInterval=0` disabled _hot_ deployment so that only static deployment will be possible (see also xref:og-deploy-hot-static[here] for more information).
diff --git a/jetty-documentation/src/main/asciidoc/operations-guide/modules/module-http.adoc b/jetty-documentation/src/main/asciidoc/operations-guide/modules/module-http.adoc
new file mode 100644
index 00000000000..7044dac497b
--- /dev/null
+++ b/jetty-documentation/src/main/asciidoc/operations-guide/modules/module-http.adoc
@@ -0,0 +1,64 @@
+//
+// ========================================================================
+// Copyright (c) 1995-2020 Mort Bay Consulting Pty Ltd and others.
+//
+// This program and the accompanying materials are made available under
+// the terms of the Eclipse Public License 2.0 which is available at
+// https://www.eclipse.org/legal/epl-2.0
+//
+// This Source Code may also be made available under the following
+// Secondary Licenses when the conditions for such availability set
+// forth in the Eclipse Public License, v. 2.0 are satisfied:
+// the Apache License v2.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-http]]
+==== Module `http`
+
+The `http` module provides support for the clear-text HTTP/1.1 protocol and depends on the xref:og-module-server[`server` module].
+
+The module file is `$JETTY_HOME/modules/http.mod`:
+
+----
+include::{JETTY_HOME}/modules/http.mod[]
+----
+
+Among the configurable properties, the most relevant are:
+
+* `jetty.http.port`, default `8080`, is the network port that Jetty listens to for clear-text HTTP/1.1 connections.
+* `jetty.http.idleTimeout`, default `30` seconds, is the amount of time a connection can be idle (i.e. no bytes received and no bytes sent) until the server decides to close it to save resources.
+* `jetty.http.acceptors`, default -1 (i.e. an accept heuristic decides the value based on the number of cores), is the number of threads that compete to accept connections.
+* `jetty.http.selectors`, default -1 (i.e. a select heuristic decides the value based on the number of cores), is the number of NIO selectors (with an associated thread) that manage connections.
+
+[[og-module-http-acceptors]]
+===== Configuration of Acceptors
+
+Accepting connections is a blocking operation, so a thread is blocked in the `accept()` call until a connection is accepted, and other threads are blocked on the lock acquired just before the `accept()` call.
+
+When the accepting thread accepts a connection, it performs a little processing of the just accepted connection, before forwarding it to other components.
+
+During this little processing other connections may be established; if there is only one accepting thread, the newly established connections are waiting for the accepting thread to finish the processing of the previously accepted connection and call again `accept()`.
+
+Servers that manage a very high number of connections that may (naturally) come and go, or that handle inefficient protocols that open and close connections very frequently (such as HTTP/1.0) may benefit of an increased number of acceptor threads.
+
+// TODO: expand on acceptors=0 and non-blocking accepts
+
+[[og-module-http-selectors]]
+===== Configuration of Selectors
+
+Performing a NIO `select()` call is a blocking operation, where the selecting thread is blocked in the `select()` call until at least one connection is ready to be processed for an I/O operation.
+There are 4 I/O operations: ready to be accepted, ready to be connected, ready to be read and ready to be written.
+
+A single NIO selector can manage thousands of connections, with the assumption that not many of them will be ready at the same time.
+
+For a single NIO selector, the ratio between the average number of selected connections over the total number of connections for every `select()` call depends heavily on the protocol but also on the application.
+
+Multiplexed protocols such as HTTP/2 tend to be busier than duplex protocols such as HTTP/1.1, leading to a higher ratio.
+
+REST applications that exchange many little JSON messages tend to be busier than file server applications, leading to a higher ratio.
+
+The higher the ratio, the higher the number of selectors you want to have, compatibly with the number of cores -- there is no point in having 64 selector threads on a single core hardware.
diff --git a/jetty-documentation/src/main/asciidoc/operations-guide/modules/module-https.adoc b/jetty-documentation/src/main/asciidoc/operations-guide/modules/module-https.adoc
new file mode 100644
index 00000000000..e8c14c6f591
--- /dev/null
+++ b/jetty-documentation/src/main/asciidoc/operations-guide/modules/module-https.adoc
@@ -0,0 +1,28 @@
+//
+// ========================================================================
+// Copyright (c) 1995-2020 Mort Bay Consulting Pty Ltd and others.
+//
+// This program and the accompanying materials are made available under
+// the terms of the Eclipse Public License 2.0 which is available at
+// https://www.eclipse.org/legal/epl-2.0
+//
+// This Source Code may also be made available under the following
+// Secondary Licenses when the conditions for such availability set
+// forth in the Eclipse Public License, v. 2.0 are satisfied:
+// the Apache License v2.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-https]]
+==== Module `https`
+
+The `https` module provides the HTTP/1.1 protocol to the xref:og-module-ssl[`ssl` module].
+
+The module file is `$JETTY_HOME/modules/https.mod`:
+
+----
+include::{JETTY_HOME}/modules/https.mod[]
+----
diff --git a/jetty-documentation/src/main/asciidoc/operations-guide/modules/module-server.adoc b/jetty-documentation/src/main/asciidoc/operations-guide/modules/module-server.adoc
new file mode 100644
index 00000000000..a4fdcad7c2e
--- /dev/null
+++ b/jetty-documentation/src/main/asciidoc/operations-guide/modules/module-server.adoc
@@ -0,0 +1,36 @@
+//
+// ========================================================================
+// Copyright (c) 1995-2020 Mort Bay Consulting Pty Ltd and others.
+//
+// This program and the accompanying materials are made available under
+// the terms of the Eclipse Public License 2.0 which is available at
+// https://www.eclipse.org/legal/epl-2.0
+//
+// This Source Code may also be made available under the following
+// Secondary Licenses when the conditions for such availability set
+// forth in the Eclipse Public License, v. 2.0 are satisfied:
+// the Apache License v2.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-server]]
+==== Module `server`
+
+The `server` module provides generic server support, and configures generic HTTP properties that apply to all HTTP protocols, the scheduler properties and the server specific properties.
+
+The `server` module depends on the xref:og-module-threadpool[`threadpool` module], the xref:og-module-bytebufferpool[`bytebufferpool` module] and the xref:og-module-logging[`logging` module].
+
+The module file is `$JETTY_HOME/modules/server.mod`:
+
+----
+include::{JETTY_HOME}/modules/server.mod[]
+----
+
+Among the configurable properties, the most relevant are:
+
+TODO
+
+// TODO: consider extracting the httpConfig and scheduler properties into separate files.
diff --git a/jetty-documentation/src/main/asciidoc/operations-guide/modules/module-ssl.adoc b/jetty-documentation/src/main/asciidoc/operations-guide/modules/module-ssl.adoc
new file mode 100644
index 00000000000..11b105ec44d
--- /dev/null
+++ b/jetty-documentation/src/main/asciidoc/operations-guide/modules/module-ssl.adoc
@@ -0,0 +1,32 @@
+//
+// ========================================================================
+// Copyright (c) 1995-2020 Mort Bay Consulting Pty Ltd and others.
+//
+// This program and the accompanying materials are made available under
+// the terms of the Eclipse Public License 2.0 which is available at
+// https://www.eclipse.org/legal/epl-2.0
+//
+// This Source Code may also be made available under the following
+// Secondary Licenses when the conditions for such availability set
+// forth in the Eclipse Public License, v. 2.0 are satisfied:
+// the Apache License v2.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-ssl]]
+==== Module `ssl`
+
+The `ssl` module provides the secure connector, and allows you to configure the keystore properties and the TLS parameters.
+
+The module file is `$JETTY_HOME/modules/ssl.mod`:
+
+----
+include::{JETTY_HOME}/modules/ssl.mod[]
+----
+
+Among the configurable properties, the most relevant are:
+
+TODO
diff --git a/jetty-documentation/src/main/asciidoc/operations-guide/modules/module-test-keystore.adoc b/jetty-documentation/src/main/asciidoc/operations-guide/modules/module-test-keystore.adoc
new file mode 100644
index 00000000000..eee9a0a42a0
--- /dev/null
+++ b/jetty-documentation/src/main/asciidoc/operations-guide/modules/module-test-keystore.adoc
@@ -0,0 +1,31 @@
+//
+// ========================================================================
+// Copyright (c) 1995-2020 Mort Bay Consulting Pty Ltd and others.
+//
+// This program and the accompanying materials are made available under
+// the terms of the Eclipse Public License 2.0 which is available at
+// https://www.eclipse.org/legal/epl-2.0
+//
+// This Source Code may also be made available under the following
+// Secondary Licenses when the conditions for such availability set
+// forth in the Eclipse Public License, v. 2.0 are satisfied:
+// the Apache License v2.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-test-keystore]]
+==== Module `test-keystore`
+
+The `test-keystore` module provides a keystore containing a self-signed certificate for domain `localhost`.
+
+The module file is `$JETTY_HOME/modules/test-keystore.mod`:
+
+----
+include::{JETTY_HOME}/modules/test-keystore.mod[]
+----
+
+Note how properties `jetty.sslContext.keyStorePath` and `jetty.sslContext.keyStorePassword` are configured, only if not already set (via the `?=` operator), directly in the module file, rather than in a `+*.ini+` file.
+This is done to avoid that these properties accidentally overwrite a real keystore configuration.
diff --git a/jetty-documentation/src/main/asciidoc/operations-guide/modules/module-threadpool.adoc b/jetty-documentation/src/main/asciidoc/operations-guide/modules/module-threadpool.adoc
new file mode 100644
index 00000000000..4b944b6d2e2
--- /dev/null
+++ b/jetty-documentation/src/main/asciidoc/operations-guide/modules/module-threadpool.adoc
@@ -0,0 +1,34 @@
+//
+// ========================================================================
+// Copyright (c) 1995-2020 Mort Bay Consulting Pty Ltd and others.
+//
+// This program and the accompanying materials are made available under
+// the terms of the Eclipse Public License 2.0 which is available at
+// https://www.eclipse.org/legal/epl-2.0
+//
+// This Source Code may also be made available under the following
+// Secondary Licenses when the conditions for such availability set
+// forth in the Eclipse Public License, v. 2.0 are satisfied:
+// the Apache License v2.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-threadpool]]
+==== Module `threadpool`
+
+The `threadpool` module allows you to configure the server-wide thread pool.
+
+// TODO: thread pool per connector should be documented here?
+
+The module file is `$JETTY_HOME/modules/threadpool.mod`:
+
+----
+include::{JETTY_HOME}/modules/threadpool.mod[]
+----
+
+Among the configurable properties, the most relevant are:
+
+TODO
diff --git a/jetty-documentation/src/main/asciidoc/operations-guide/modules/modules.adoc b/jetty-documentation/src/main/asciidoc/operations-guide/modules/modules.adoc
new file mode 100644
index 00000000000..c9aa42caa99
--- /dev/null
+++ b/jetty-documentation/src/main/asciidoc/operations-guide/modules/modules.adoc
@@ -0,0 +1,27 @@
+//
+// ========================================================================
+// Copyright (c) 1995-2020 Mort Bay Consulting Pty Ltd and others.
+//
+// This program and the accompanying materials are made available under
+// the terms of the Eclipse Public License 2.0 which is available at
+// https://www.eclipse.org/legal/epl-2.0
+//
+// This Source Code may also be made available under the following
+// Secondary Licenses when the conditions for such availability set
+// forth in the Eclipse Public License, v. 2.0 are satisfied:
+// the Apache License v2.0 which is available at
+// https://www.apache.org/licenses/LICENSE-2.0
+//
+// SPDX-License-Identifier: EPL-2.0 OR Apache-2.0
+// ========================================================================
+//
+
+[[og-modules]]
+==== Jetty Modules
+
+TODO
+// Consider:
+// * old_docs/gettingstarted/configuring/*.adoc
+// * old_docs/startup/startup-modules.adoc
+// * old_docs/startup/custom-modules.adoc
+//
diff --git a/jetty-documentation/src/main/asciidoc/operations-guide/old_docs/contexts/chapter.adoc b/jetty-documentation/src/main/asciidoc/operations-guide/old_docs/contexts/chapter.adoc
index d171d12fb5d..abe1de08689 100644
--- a/jetty-documentation/src/main/asciidoc/operations-guide/old_docs/contexts/chapter.adoc
+++ b/jetty-documentation/src/main/asciidoc/operations-guide/old_docs/contexts/chapter.adoc
@@ -22,8 +22,6 @@
This chapter discusses various options for configuring Jetty contexts.
include::setting-context-path.adoc[]
-include::configuring-virtual-hosts.adoc[]
include::temporary-directories.adoc[]
-include::serving-webapp-from-particular-port.adoc[]
include::custom-error-pages.adoc[]
include::setting-form-size.adoc[]
diff --git a/jetty-documentation/src/main/asciidoc/operations-guide/old_docs/contexts/configuring-virtual-hosts.adoc b/jetty-documentation/src/main/asciidoc/operations-guide/old_docs/contexts/configuring-virtual-hosts.adoc
deleted file mode 100644
index 5dca037769d..00000000000
--- a/jetty-documentation/src/main/asciidoc/operations-guide/old_docs/contexts/configuring-virtual-hosts.adoc
+++ /dev/null
@@ -1,216 +0,0 @@
-//
-// ========================================================================
-// Copyright (c) 1995-2020 Mort Bay Consulting Pty Ltd and others.
-//
-// This program and the accompanying materials are made available under
-// the terms of the Eclipse Public License 2.0 which is available at
-// https://www.eclipse.org/legal/epl-2.0
-//
-// This Source Code may also be made available under the following
-// Secondary Licenses when the conditions for such availability set
-// forth in the Eclipse Public License, v. 2.0 are satisfied:
-// the Apache License v2.0 which is available at
-// https://www.apache.org/licenses/LICENSE-2.0
-//
-// SPDX-License-Identifier: EPL-2.0 OR Apache-2.0
-// ========================================================================
-//
-
-[[configuring-virtual-hosts]]
-=== Configuring Virtual Hosts
-
-A virtual host is an alternative name, registered in DNS, for an IP address such that multiple domain names will resolve to the same IP of a shared server instance.
-If the content to be served to the aliases names is link:#different-virtual-hosts-different-contexts[different], then a virtual host needs to be configured for each deployed link:{JDURL}/org/eclipse/jetty/server/handler/ContextHandler.html[context] to indicate which names a context will respond to.
-
-Virtual hosts are set on a link:{JDURL}/org/eclipse/jetty/server/handler/ContextHandler.html[context] by calling the link:{JDURL}/org/eclipse/jetty/server/handler/ContextHandler.html#setVirtualHosts-java.lang.String:A-[`setVirtualHosts`] or link:{JDURL}/org/eclipse/jetty/server/handler/ContextHandler.html#addVirtualHosts-java.lang.String:A-[`addVirtualHost`] method which can be done in several ways:
-
-* Using a link:#deployable-descriptor-file[context XML] file in the webapps directory (see the example in link:{GITBROWSEURL}/tests/test-webapps/test-jetty-webapp/src/main/config/demo-base/webapps/test.xml[test.xml] in the Jetty distribution).
-* Creating a link:#deployment-architecture[custom deployer] with a binding to configure virtual hosts for all contexts found in the same `webapps` directory.
-* Calling the link:{JDURL}/org/eclipse/jetty/server/handler/ContextHandler.html#setVirtualHosts-java.lang.String:A-[API] directly on an link:#advanced-embedding[embedded] usage.
-* Using a `WEB-INF/jetty-web.xml` file (now deprecated).
-
-[[configuring-a-virtual-host]]
-==== Virtual Host Names
-
-Jetty supports the following styles of virtual host name:
-
-www.hostname.com::
- A fully qualified host name. It is important to list all variants as a site may receive traffic from both www.hostname.com and just hostname.com
-*.hostname.com::
- A wildcard qualified host which will match only one level of arbitrary names.
- *.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 given as a virtual host name to indicate that a context should handle requests received on that server port that do not have a host name specified (HTTP/0.9 or HTTP/1.0).
-@ConnectorName::
- A connector name, which is not strictly a virtual host, but instead will only match requests that are received on connectors that have a matching name set with link:{JDURL}/org/eclipse/jetty/server/AbstractConnector.html#setName(java.lang.String)[Connector.setName(String)].
-www.√integral.com::
- Non-ASCII and http://en.wikipedia.org/wiki/Internationalized_domain_name[IDN] domain names can be set as virtual hosts using http://en.wikipedia.org/wiki/Punycode[Puny Code] equivalents that may be obtained from a http://network-tools.com/idn-convert.asp[Punycode/IDN converters].
- For example if the non-ASCII domain name `www.√integral.com` is given to a browser, then it 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.
-
-==== Example Virtual Host Configuration
-
-Virtual hosts can be used with any context that is a subclass of link:{JDURL}/org/eclipse/jetty/server/handler/ContextHandler.html[ContextHandler].
-Lets look at an example where we configure a web application - represented by the link:{JDURL}/org/eclipse/jetty/webapp/WebAppContext.html[WebAppContext] class - with virtual hosts.
-You supply a list of IP addresses and names at which the web application is reachable, such as the following:
-
-* `333.444.555.666`
-* `127.0.0.1`
-* `www.blah.com`
-* `www.blah.net`
-* `www.blah.org`
-
-Suppose you have a webapp called `blah.war`, that you want all of the above names and addresses to be served at path "`/blah`".
-Here's how you would configure the virtual hosts with a link:#deployable-descriptor-file[context XML] file:
-
-[source, xml, subs="{sub-order}"]
-----
-
-
-
-
- /blah
- blah.war
-
-
- - 333.444.555.666
- - 127.0.0.1
- - www.blah.com
- - www.blah.net
- - www.blah.org
-
-
-
-----
-
-[[different-virtual-hosts-different-contexts]]
-==== Using Different Sets of Virtual Hosts to Select Different Contexts
-
-You can configure different contexts to respond on different virtual hosts by supplying a specific list of virtual hosts for each one.
-
-For example, suppose your imaginary machine has these DNS names:
-
-* `www.blah.com`
-* `www.blah.net`
-* `www.blah.org`
-* `www.other.com`
-* `www.other.net`
-* `www.other.org`
-
-Suppose also you have 2 webapps, one called `blah.war` that you would like served from the `*.blah.*` names, and one called `other.war` that you want served only from the `*.other.*` names.
-
-Using the method of preparing link:#deployable-descriptor-file[contextXML] files, one for each webapp yields the following:
-
-For `blah` webapp:
-
-[source, xml, subs="{sub-order}"]
-----
-
-
-
-
- /blah
- /blah.war
-
-
- - www.blah.com
- - www.blah.net
- - www.blah.org
-
-
-
-----
-
-These URLs now resolve to the blah context (ie `blah.war`):
-
-* `http://www.blah.com/blah`
-* `http://www.blah.net/blah`
-* `http://www.blah.org/blah`
-
-For `other` webapp:
-
-[source, xml, subs="{sub-order}"]
-----
-
-
-
-
- /other
- /other.war
-
-
- - www.other.com
- - www.other.net
- - www.other.org
-
-
-
-----
-
-These URLs now resolve to the other context (i.e. `other.war`):
-
-* `http://www.other.com/other`
-* `http://www.other.net/other`
-* `http://www.other.org/other`
-
-[[different-virtual-hosts-different-context-same-path]]
-==== Using Different Sets of Virtual Hosts to Select Different Contexts at the Same Context Path
-
-In the previous section we setup 2 different contexts to be served from different virtual hosts at _different_ context paths.
-However, there is no requirement that the context paths must be distinct: you may use the same context path for multiple contexts, and use virtual hosts to determine which one is served for a given request.
-
-Consider an example where we have the same set of DNS names as before, and the same webapps `blah.war` and `other.war`. We still want `blah.war` to be served in response to hostnames of `*.blah.*`, and we still want `other.war` to be served in response to `*.other.*` names.
-However, we would like__all__ of our clients to use the `"/"` context path, no matter which context is being targeted.
-
-In other words, we want all of the following URLs to map to `blah.war`:
-
-* `http://www.blah.com/`
-* `http://www.blah.net/`
-* `http://www.blah.org/`
-
-Similarly, we want the following URLs to map to `other.war`:
-
-* `http://www.other.com/`
-* `http://www.other.net/`
-* `http://www.other.org/`
-
-To achieve this, we simply use the same context path of `/` for each of our webapps, while still applying our different set of virtual host names.
-
-For foo webapp:
-
-[source, xml, subs="{sub-order}"]
-----
-
-
-
-
- /
- /foo.war
-
-
- - www.blah.com
- - www.blah.net
- - www.blah.org
-
-
-
-----
-
-For bar webapp:
-
-[source, xml, subs="{sub-order}"]
-----
-
-
-
-
- /
- /bar.war
-
-
- - www.other.com
- - www.other.net
- - www.other.org
-
-
-
-----
diff --git a/jetty-documentation/src/main/asciidoc/operations-guide/old_docs/contexts/serving-webapp-from-particular-port.adoc b/jetty-documentation/src/main/asciidoc/operations-guide/old_docs/contexts/serving-webapp-from-particular-port.adoc
deleted file mode 100644
index 4c1c353527d..00000000000
--- a/jetty-documentation/src/main/asciidoc/operations-guide/old_docs/contexts/serving-webapp-from-particular-port.adoc
+++ /dev/null
@@ -1,74 +0,0 @@
-//
-// ========================================================================
-// Copyright (c) 1995-2020 Mort Bay Consulting Pty Ltd and others.
-//
-// This program and the accompanying materials are made available under
-// the terms of the Eclipse Public License 2.0 which is available at
-// https://www.eclipse.org/legal/epl-2.0
-//
-// This Source Code may also be made available under the following
-// Secondary Licenses when the conditions for such availability set
-// forth in the Eclipse Public License, v. 2.0 are satisfied:
-// the Apache License v2.0 which is available at
-// https://www.apache.org/licenses/LICENSE-2.0
-//
-// SPDX-License-Identifier: EPL-2.0 OR Apache-2.0
-// ========================================================================
-//
-
-[[serving-webapp-from-particular-port]]
-=== Serving a WebApp from a Particular Port/Connector
-
-Sometimes it is required to serve different web applications from different ports/connectors.
-The simplest way to do this is to create multiple `Server` instances.
-However, if contexts need to share resources (eg data sources, authentication), or if the mapping of ports to web applications is not cleanly divided, then the named connector mechanism can be used.
-
-[[creating-server-instances]]
-==== Creating Multiple Server Instances
-
-Creating multiple server instances is a straight forward process that includes embedding Jetty code by creating multiples instances of the Server class and configuring them as needed.
-This is also easy to achieve if you are configuring Jetty servers via XML.
-The `id` field in the Configure element of `jetty.xml` files is used to identify the instance that the configuration applies to, so to run two instances of the Server, you can copy the `jetty.xml`, jetty-http.xml and other jetty configuration files used and change the "Server" id to a new name.
-This can be done in the same style and layout as the existing `jetty.xml` files or the multiple XML files may be combined to a single file.
-
-When creating new configurations for alternative server:
-
-* Change all `id="Server"` to the new server name:
-
-[source, xml, subs="{sub-order}"]
-----
-
-----
-
-* For all connectors for the new server change the `refid` in the server argument:
-
-[source, xml, subs="{sub-order}"]
-----
-