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 |
In the http.ini
file you can find the following (among other contents):
--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
:
--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
|
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 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.