Architecture Overview

Jetty is an HTTP server and Servlet Container, and supports deployments of web applications.

The Jetty server listens on one or more network ports using one or more protocol connectors.

Clients send HTTP requests for specific URIs, such as https://host/store/cart.

The HTTP requests arrive to the connectors through the network; the Jetty server processes the requests and, based on their URIs, forwards them to the appropriate deployed web application.

Diagram

Main Concepts

There are three main concepts on which the Jetty standalone server is based:

  • The Jetty module system, where Jetty modules provides Jetty features.

  • The $JETTY_BASE directory, that provides a place where you configure which Jetty modules you want to enable, configure the properties of each enabled module, and therefore configure the features you need for your web applications.

  • The Jetty start mechanism, that starts a JVM that runs Jetty with the configuration you specified.

After installing Jetty, you will want to set up a $JETTY_BASE directory where you configure Jetty modules.

Jetty Modules

The Jetty standalone server is made of Java components that are assembled together, configured and started to provide different features.

A Jetty module provides one or more components that work together to provide typically one feature, although they may provide more than one feature.

A Jetty module is nothing more than Jetty components assembled together like you would do using Java APIs, just done in a declarative way using configuration files. What you can do in Java code to assemble Jetty components can be done using Jetty modules.

A Jetty module may be dependent on other Jetty modules: for example, the http Jetty module depends on the server Jetty module which in turn depends on the threadpool and logging Jetty modules.

Every feature in a Jetty server is enabled by enabling the corresponding Jetty module(s).

For example, if you enable only the http Jetty module, then your Jetty standalone server will only be able to listen to a network port for clear-text HTTP requests. It will not be able to process secure HTTP (i.e. https) requests, it will not be able to process WebSocket, or HTTP/2, or HTTP/3 or any other protocol because the correspondent modules have not been enabled.

You can even start a Jetty server without listening on a network port — for example because you have enabled a custom module you wrote that provides the features you need.

This allows the Jetty standalone server to be as small as necessary: modules that are not enabled are not loaded, don’t waste memory, and you don’t risk a client using a module that you did not know was even there.

For more detailed information about the Jetty module system, see this section.

$JETTY_HOME and $JETTY_BASE

Instead of managing multiple Jetty distributions out of many locations, it is possible to maintain a separation between the binary installation of the standalone Jetty, known as $JETTY_HOME, and the customizations for your specific environment(s), known as $JETTY_BASE.

This separation between the binary installation directory and the specific configuration directory allows managing multiple, different, server configurations, and allows for quick, drop-in upgrades of Jetty.

There should always only be one $JETTY_HOME (per version of Jetty), but there can be many $JETTY_BASE directories that reference it.

This separation between $JETTY_HOME and $JETTY_BASE allows Jetty upgrades without affecting your web applications. $JETTY_HOME contains the Jetty runtime and libraries and the default configuration, while a $JETTY_BASE contains your web applications and any override of the default configuration.

For example, with the $JETTY_HOME installation the default value for the network port for clear-text HTTP is 8080. However, you may want that port to be 6060, because Jetty is behind a load balancer that is configured to forward to the backend on port 6060. In this case, you configure the clear-text HTTP port in $JETTY_BASE, not in $JETTY_HOME. When you upgrade Jetty, you will upgrade only the files in $JETTY_HOME, and all the configuration in $JETTY_BASE will remain unchanged, keeping your clear-text HTTP port at 6060.

Installing the Jetty runtime and libraries in $JETTY_HOME also allows you to leverage file system permissions: $JETTY_HOME may be owned by an administrator user (so that only administrators can upgrade it), while $JETTY_BASE directories may be owned by a less privileged user.

If you had changed the default configuration in $JETTY_HOME, when you upgrade Jetty, say from version 10.0.0 to version 10.0.1, your changes would be lost. Maintaining all the changes in $JETTY_HOME, and having to reconfigure these with each upgrade results in a massive commitment of time and effort.

To recap:

$JETTY_HOME

This is the location for the Jetty binaries.

$JETTY_BASE

This is the location for your configurations and customizations to the Jetty binaries.

Start Mechanism

The Jetty start mechanism provides two features:

  • The mean to configure your $JETTY_BASE by enabling the desired modules, and to display the configuration of your $JETTY_BASE.

  • The mean to start Jetty itself, by starting a JVM that reads the Jetty configuration in $JETTY_BASE, which is then executed to assemble and start the Jetty components.

The Jetty start mechanism is invoked by executing $JETTY_HOME/start.jar from within your $JETTY_BASE, and you can think of it as the Jetty command line program, similar to many Unix/Windows command line programs.

For example, you can ask for help:

$ java -jar $JETTY_HOME/start.jar --help

Or you can list all available modules (or only those with a specific tag):

# List all the modules.
$ java -jar $JETTY_HOME/start.jar --list-modules=*

# List all the modules tagged as "demo".
$ java -jar $JETTY_HOME/start.jar --list-modules=demo

You can enable a module, for example the http module:

$ java -jar $JETTY_HOME/start.jar --add-modules=http

Once you have one or more module enabled, you can display the current configuration, to verify that the configuration is correct:

$ java -jar $JETTY_HOME/start.jar --list-config

You can enable a Jetty demo module, which will deploy a demo web application:

$ java -jar $JETTY_HOME/start.jar --add-modules=demo-simple

Finally, you can start Jetty:

$ java -jar $JETTY_HOME/start.jar

Read more information at the Jetty start mechanism section.