Getting Started

If you are new to Eclipse Jetty, read on to download, install, start and deploy web applications to Jetty.

Quick Setup

Jetty is distributed in an artifact that expands in a directory called $JETTY_HOME, which should not be modified.

Configuration for Jetty is typically done in a directory called $JETTY_BASE. There may be more than one $JETTY_BASE directories with different configurations.

Jetty supports the deployment of EE8, EE9 and EE10 standard web applications, as well as the deployment of Jetty-specific web applications.

For example, the following commands can be used to set up a $JETTY_BASE directory that supports deployment of EE10 *.war files and a clear-text HTTP connector:

$ export JETTY_HOME=/path/to/jetty-home
$ mkdir /path/to/jetty-base
$ cd /path/to/jetty-base
$ java -jar $JETTY_HOME/start.jar --add-modules=server,http,ee10-deploy

The last command creates a $JETTY_BASE/start.d/ directory and other directories that contain the configuration of the server, including the $JETTY_BASE/webapps/ directory, in which standard EE10 *.war files can be deployed.

To deploy Jetty’s demo web applications, run this command:

$ java -jar $JETTY_HOME/start.jar --add-module=demos

Now you can start the Jetty server with:

$ java -jar $JETTY_HOME/start.jar

Point your browser at http://localhost:8080 to see the demo web applications deployed in Jetty.

The Jetty server can be stopped with ctrl+c in the terminal window.

The following sections will guide you in details about downloading, installing and starting Jetty, and deploying your web applications to Jetty.

Read the Jetty architecture section for more information about Jetty modules, $JETTY_HOME, $JETTY_BASE and how to customize and start Jetty.

Downloading Jetty

The Jetty distribution is a file of the form jetty-home-<version>.<ext>, available for download from https://jetty.org/download.html

The 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 operating systems.

Installing Jetty

After the download, unpacking 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 12.0.15-SNAPSHOT will create a directory called jetty-home-12.0.15-SNAPSHOT.

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 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}.

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 Jetty architecture section to become familiar with the terms used in this documentation. Otherwise, you can jump to the section on starting Jetty.

Starting Jetty

Jetty as a standalone server has no graphical user interface; configuring and running the server is done from the command line.

First, create a $JETTY_BASE directory.

$ JETTY_BASE=/path/to/jetty.base
$ mkdir $JETTY_BASE
$ cd $JETTY_BASE

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
ERROR : No enabled jetty modules found!
INFO  : ${jetty.home} = /path/to/jetty.home
INFO  : ${jetty.base} = /path/to/jetty.home-base
ERROR : Please create and/or configure a ${jetty.base} directory.

Usage: java -jar $JETTY_HOME/start.jar [options] [properties] [configs]
       java -jar $JETTY_HOME/start.jar --help  # for more information

Jetty uses a module system to configure and assemble the server; these modules are enabled and configured in $JETTY_BASE. Since the $JETTY_BASE directory you just created is empty, Jetty has no configuration it can use to assemble the server.

See the architecture section of this document for more information on the design of Jetty’s module system.

You can explore what modules are available with the --list-modules flag:

$ java -jar $JETTY_HOME/start.jar --list-modules=*

Now try to enable the http module.

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 this section.
$ java -jar $JETTY_HOME/start.jar --add-modules=http
INFO  : mkdir ${jetty.base}/start.d
INFO  : server          transitively enabled, ini template available with --add-modules=server
INFO  : logging-jetty   transitively enabled
INFO  : http            initialized in ${jetty.base}/start.d/http.ini
INFO  : resources       transitively enabled
INFO  : threadpool      transitively enabled, ini template available with --add-modules=threadpool
INFO  : logging/slf4j   dynamic dependency of logging-jetty
INFO  : bytebufferpool  transitively enabled, ini template available with --add-modules=bytebufferpool
INFO  : mkdir ${jetty.base}/resources
INFO  : copy ${jetty.home}/modules/logging/jetty/resources/jetty-logging.properties to ${jetty.base}/resources/jetty-logging.properties
INFO  : Base directory was modified

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
2024-10-01 18:00:44.845:INFO :oejs.Server:main: jetty-12.0.15-SNAPSHOT; built: 2024-10-01T17:53:16.597Z; git: e9d61a16862f18d4c20f422e490e27e66c38d684; jvm 23+37
2024-10-01 18:00:44.933:INFO :oejs.AbstractConnector:main: Started ServerConnector@17c2186a{HTTP/1.1, (http/1.1)}{0.0.0.0:8080}
2024-10-01 18:00:44.971:INFO :oejs.Server:main: Started oejs.Server@43bc63a3{STARTING}[12.0.15-SNAPSHOT,sto=5000] @2104ms

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 you deploy your first web application, take a moment to see what happened to the $JETTY_BASE directory once you enabled the http module:

$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.
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 http module properties.

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 (among other contents):

http.ini
--module=http (1)
# jetty.http.port=8080 (2)
...
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.

Try changing the default port. Open http.ini, uncomment the line containing jetty.http.port=, and change its value to 9999:

http.ini
--module=http
jetty.http.port=9999
...

If you restart Jetty, it will use this new value:

$ java -jar $JETTY_HOME/start.jar
2024-10-01 18:00:47.327:INFO :oejs.Server:main: jetty-12.0.15-SNAPSHOT; built: 2024-10-01T17:53:16.597Z; git: e9d61a16862f18d4c20f422e490e27e66c38d684; jvm 23+37
2024-10-01 18:00:47.388:INFO :oejs.AbstractConnector:main: Started ServerConnector@17c2186a{HTTP/1.1, (http/1.1)}{0.0.0.0:9999}
2024-10-01 18:00:47.411:INFO :oejs.Server:main: Started oejs.Server@43bc63a3{STARTING}[12.0.15-SNAPSHOT,sto=5000] @1893ms

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
2024-10-01 18:00:49.822:INFO :oejs.Server:main: jetty-12.0.15-SNAPSHOT; built: 2024-10-01T17:53:16.597Z; git: e9d61a16862f18d4c20f422e490e27e66c38d684; jvm 23+37
2024-10-01 18:00:49.887:INFO :oejs.AbstractConnector:main: Started ServerConnector@17c2186a{HTTP/1.1, (http/1.1)}{0.0.0.0:8080}
2024-10-01 18:00:49.900:INFO :oejs.Server:main: Started oejs.Server@43bc63a3{STARTING}[12.0.15-SNAPSHOT,sto=5000] @1950ms

For more detailed information about the Jetty start mechanism, you can read the Jetty start mechanism section.

Deploying Web Applications

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. Their deployment is described in this section.

  • Jetty context XML files, that allow you to customize the deployment of standard web applications, and also allow you to use Jetty components — and possibly custom components written by you — to assemble and deploy your web applications. Their deployment is described in this section.

Jetty supports the deployment of both standard web applications and Jetty context XML files in a specific EE environment, such as the old Java EE 8, or Jakarta EE 9, or Jakarta EE 10.

Jetty supports simultaneous deployment of web applications each to a possibly different environment, for example an old Java EE 8 web application alongside a new Jakarta EE 10 web application.

Refer to the section about deployment for further information about how to deploy to different environments.

In the following sections you can find simple examples of deployments of Jakarta EE 10 web applications.

Deploying *.war Files

A standard Servlet web application is packaged in either a *.war file or in a directory with the structure of a *.war file.

Recall that the structure of a *.war file is as follows:

mywebapp.war
├── index.html (1)
└── WEB-INF (2)
    ├── classes/ (3)
    ├── lib/ (4)
    └── web.xml (5)
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’s compiled *.class files
4 WEB-INF/lib 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 ee10-deploy module.

The following examples assume you’re deploying a Jakarta EE 10 application; for other versions of Jakarta EE, make sure to activate the corresponding ee{8,9,10}-deploy module.

Refer to the section about deployment for further information about how to deploy to different environments.

$ java -jar $JETTY_HOME/start.jar --add-modules=ee10-deploy
INFO  : sessions        transitively enabled, ini template available with --add-modules=sessions
INFO  : security        transitively enabled
INFO  : ee10-deploy     initialized in ${jetty.base}/start.d/ee10-deploy.ini
INFO  : ee10-security   transitively enabled
INFO  : ee-webapp       transitively enabled, ini template available with --add-modules=ee-webapp
INFO  : ee10-webapp     transitively enabled, ini template available with --add-modules=ee10-webapp
INFO  : ee10-servlet    transitively enabled
INFO  : deploy          transitively enabled
INFO  : mkdir ${jetty.base}/webapps
INFO  : Base directory was modified

The ee10-deploy module creates $JETTY_BASE/webapps, which is the directory where Jetty looks for any *.war files or web application directories to deploy.

Activating one of Jetty’s ee{8,9,10}-deploy modules 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 protocol modules have been enabled. Refer to the section about protocols for further information.

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-modules=ee10-demo-simple

The $JETTY_BASE directory is now:

$JETTY_BASE
├── resources
│   └── jetty-logging.properties
├── start.d
│   ├── deploy.ini
│   ├── ee10-demo-simple.ini
│   └── http.ini
└── webapps
    └── ee10-demo-simple.war

Now start Jetty:

$ java -jar $JETTY_HOME/start.jar
2024-10-01 18:00:55.988:INFO :oejs.Server:main: jetty-12.0.15-SNAPSHOT; built: 2024-10-01T17:53:16.597Z; git: e9d61a16862f18d4c20f422e490e27e66c38d684; jvm 23+37
2024-10-01 18:00:56.029:INFO :oejdp.ScanningAppProvider:main: Deployment monitor ee10 in [file:///path/to/jetty.home-base/webapps/] at intervals 0s
2024-10-01 18:00:56.045:INFO :oejd.DeploymentManager:main: addApp: App@2ed2d9cb[ee10,null,/path/to/jetty.home-base/webapps/ee10-demo-simple.war]
2024-10-01 18:00:56.379:INFO :oejew.StandardDescriptorProcessor:main: NO JSP Support for /ee10-demo-simple, did not find org.eclipse.jetty.ee10.jsp.JettyJspServlet
2024-10-01 18:00:56.416:INFO :oejsh.ContextHandler:main: Started oeje10w.WebAppContext@895e367{EE10 Demo Simple WebApp,/ee10-demo-simple,b=file:///path/to/jetty.home-base/work/jetty-0_0_0_0-8080-ee10-demo-simple_war-_ee10-demo-simple-any-/webapp/,a=AVAILABLE,h=oeje10s.SessionHandler@1b266842{STARTED}}{/path/to/jetty.home-base/webapps/ee10-demo-simple.war}
2024-10-01 18:00:56.458:INFO :oejes.ServletContextHandler:main: Started oeje10w.WebAppContext@895e367{EE10 Demo Simple WebApp,/ee10-demo-simple,b=file:///path/to/jetty.home-base/work/jetty-0_0_0_0-8080-ee10-demo-simple_war-_ee10-demo-simple-any-/webapp/,a=AVAILABLE,h=oeje10s.SessionHandler@1b266842{STARTED}}{/path/to/jetty.home-base/webapps/ee10-demo-simple.war}
2024-10-01 18:00:56.460:INFO :oejs.DefaultSessionIdManager:main: Session workerName=node0
2024-10-01 18:00:56.477:INFO :oejs.AbstractConnector:main: Started ServerConnector@30bce90b{HTTP/1.1, (http/1.1)}{0.0.0.0:8080}
2024-10-01 18:00:56.514:INFO :oejs.Server:main: Started oejs.Server@59af0466{STARTING}[12.0.15-SNAPSHOT,sto=5000] @2901ms

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/ee10-demo-simple.

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 — read this section.