Architecture Overview

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

After installing Jetty, you will want to set up a $JETTY_BASE directory where you configure 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.

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:

The Jetty start mechanism provides two features:

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:

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

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

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

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

Finally, you can start Jetty:

Read more information at the Jetty start mechanism section.