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.
The following commands can be used to set up a $JETTY_BASE
directory that supports deployment of *.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-module=server,http,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 *.war
files can be deployed.
To deploy Jetty’s demo web applications, run this command:
$ java -jar $JETTY_HOME/start.jar --add-module=demo
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 Eclipse Jetty distribution is available for download from https://jetty.org/download.html
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 operating systems.
Installing Jetty
After the download, unpacking Eclipse Jetty will extract the files into a directory called jetty-home-VERSION
, where VERSION
is the version that you downloaded, for example 11.0.24-SNAPSHOT
, so that the directory is called jetty-home-11.0.24-SNAPSHOT
.
Unpack Eclipse Jetty compressed file in a convenient location, for example under /opt
.
For Windows users, you should unpack Jetty to a path that does not contain spaces. |
The rest of the instructions in this documentation will refer to this location as $JETTY_HOME
, or ${jetty.home}
.
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. |
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
Eclipse Jetty as a standalone server has no graphical user interface, so configuring and running the server is done from the command line.
Recall from the architecture section that Jetty is based on modules, that provides features, and on $JETTY_BASE
, the place where you configure which module (and therefore which feature) you want to enable, and where you configure module parameters.
Jetty is started by executing $JETTY_HOME/start.jar
from within a $JETTY_BASE
directory, so first we need to create a $JETTY_BASE
:
$ JETTY_BASE=/path/to/jetty.base $ cd $JETTY_BASE
If you try to start Jetty from an empty $JETTY_BASE
you get:
$ 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 exited complaining that there are no modules enabled, since the $JETTY_BASE
you just created is empty and therefore there is no configuration to read to assemble the Jetty server.
However, it shows that start.jar
takes parameters, whose details can be found in this section.
You can explore what modules are available out of the box via:
$ java -jar $JETTY_HOME/start.jar --list-modules=*
Let’s try to enable the http
module (see also this section for additional information):
$ java -jar $JETTY_HOME/start.jar --add-module=http
INFO : mkdir ${jetty.base}/start.d INFO : server transitively enabled, ini template available with --add-module=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-module=threadpool INFO : logging/slf4j dynamic dependency of logging-jetty INFO : bytebufferpool transitively enabled, ini template available with --add-module=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
Now you can start Jetty:
$ java -jar $JETTY_HOME/start.jar
2024-10-01 18:02:23.298:INFO :oejs.Server:main: jetty-11.0.24-SNAPSHOT; built: 2024-10-01T17:50:47.091Z; git: 523bed3a6cb659253ddf1805d495fcdd6659dc1d; jvm 23+37 2024-10-01 18:02:23.366:INFO :oejs.AbstractConnector:main: Started ServerConnector@2f4948e4{HTTP/1.1, (http/1.1)}{0.0.0.0:8080} 2024-10-01 18:02:23.392:INFO :oejs.Server:main: Started Server@1a451d4d{STARTING}[11.0.24-SNAPSHOT,sto=5000] @1558ms
Note how Jetty is listening on port 8080
for clear-text HTTP/1.1 connections.
After having enabled the http
module, the $JETTY_BASE
directory looks like this:
JETTY_BASE
├── resources
│ └── jetty-logging.properties (1)
└── start.d (2)
└── http.ini (3)
1 | The resources/jetty-logging.properties file has been created because the http modules depends on the server module, which in turn depends on the logging module; the logging module created this file that can be configured to control the server logging level. |
2 | The start.d/ directory contains the configuration files for the modules. |
3 | The start.d/http.ini file is the http module configuration file, where you can specify values for the http module properties. |
In the http.ini
file you can find the following content (among other content):
--module=http (1)
# jetty.http.port=8080 (2)
...
1 | This line enables the http module and should not be modified. |
2 | This line is commented out and specifies the default value for the module property jetty.http.port , which is the network port that listens for clear-text HTTP connections. |
You can change the module property jetty.http.port
value directly from the command line:
$ java -jar $JETTY_HOME/start.jar jetty.http.port=9999
To make this change persistent, you can edit the http.ini
file, uncomment the module property jetty.http.port
and change its value to 9999
:
--module=http jetty.http.port=9999 ...
If you restart Jetty, the new value will be used:
$ java -jar $JETTY_HOME/start.jar
2024-10-01 18:02:25.305:INFO :oejs.Server:main: jetty-11.0.24-SNAPSHOT; built: 2024-10-01T17:50:47.091Z; git: 523bed3a6cb659253ddf1805d495fcdd6659dc1d; jvm 23+37 2024-10-01 18:02:25.371:INFO :oejs.AbstractConnector:main: Started ServerConnector@54ca0889{HTTP/1.1, (http/1.1)}{0.0.0.0:9999} 2024-10-01 18:02:25.395:INFO :oejs.Server:main: Started Server@1a451d4d{STARTING}[11.0.24-SNAPSHOT,sto=5000] @1475ms
Note how Jetty is now listening on port 9999
for clear-text HTTP/1.1 connections.
If you want to enable support for different protocols such as secure HTTP/1.1 or HTTP/2 or HTTP/3, or configure Jetty behind a load balancer, read this section. |
The Jetty server is now up and running, but it has no web applications deployed, so it just replies with 404 Not Found
to every request.
It is time to deploy your web applications to Jetty.
For more detailed information about the Jetty start mechanism, you can read the Jetty start mechanism section.
Deploying Web Applications
For the purpose of deploying web applications to Jetty, there are two types of resources that can be deployed:
-
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 use Jetty components, and possibly custom components written by you, to assemble your web applications. Their deployment is described in this section.
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 deploy
module (see the deploy
module complete definition here).
$ java -jar $JETTY_HOME/start.jar --add-module=deploy
INFO : webapp transitively enabled, ini template available with --add-module=webapp INFO : security transitively enabled INFO : servlet transitively enabled INFO : deploy initialized in ${jetty.base}/start.d/deploy.ini INFO : mkdir ${jetty.base}/webapps INFO : Base directory was modified
The deploy
module creates the $JETTY_BASE/webapps
directory, the directory where *.war
files or web application directories should be copied so that Jetty can deploy them.
The 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 modules have been enabled. Refer to the section about protocols for further information. |
Now you need to copy a web application to the $JETTY_BASE/webapps
directory, and you can use one of the demos shipped with Jetty:
$ java -jar $JETTY_HOME/start.jar --add-module=demo-simple
The $JETTY_BASE
directory is now:
$JETTY_BASE ├── resources │ └── jetty-logging.properties ├── start.d │ ├── deploy.ini │ └── http.ini └── webapps └── demo-simple.war
Now start Jetty:
$ java -jar $JETTY_HOME/start.jar
2024-10-01 18:02:29.983:INFO :oejs.Server:main: jetty-11.0.24-SNAPSHOT; built: 2024-10-01T17:50:47.091Z; git: 523bed3a6cb659253ddf1805d495fcdd6659dc1d; jvm 23+37 2024-10-01 18:02:30.039:INFO :oejdp.ScanningAppProvider:main: Deployment monitor [file:///path/to/jetty.home-base/webapps/] 2024-10-01 18:02:30.236:INFO :oejw.StandardDescriptorProcessor:main: NO JSP Support for /demo-simple, did not find org.eclipse.jetty.jsp.JettyJspServlet 2024-10-01 18:02:30.255:INFO :oejss.DefaultSessionIdManager:main: Session workerName=node0 2024-10-01 18:02:30.301:INFO :oejsh.ContextHandler:main: Started o.e.j.w.WebAppContext@6fdbe764{Simple Web Application,/demo-simple,file:///path/to/jetty.home-base/work/jetty-0_0_0_0-8080-demo-simple_war-_demo-simple-any-/webapp/,AVAILABLE}{/path/to/jetty.home-base/webapps/demo-simple.war} 2024-10-01 18:02:30.311:INFO :oejs.AbstractConnector:main: Started ServerConnector@3214ee6{HTTP/1.1, (http/1.1)}{0.0.0.0:8080} 2024-10-01 18:02:30.328:INFO :oejs.Server:main: Started Server@157853da{STARTING}[11.0.24-SNAPSHOT,sto=5000] @2098ms
Note the highlighted line that logs the deployment of demo-simple.war
.
Now you can access the web application by pointing your browser to http://localhost:8080/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, etc. read this section.