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://eclipse.dev/jetty/download.php
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.21-SNAPSHOT, so that the directory is called jetty-home-11.0.21-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-06-21 15:33:57.795:INFO :oejs.Server:main: jetty-11.0.22-SNAPSHOT; built: 2024-06-21T15:28:57.563Z; git: 3ec84034a62c56b0b42f1c85d5eee44f8c2e9136; jvm 22.0.1+8
2024-06-21 15:33:57.871:INFO :oejs.AbstractConnector:main: Started ServerConnector@408bad78{HTTP/1.1, (http/1.1)}{0.0.0.0:8080}
2024-06-21 15:33:57.897:INFO :oejs.Server:main: Started Server@56a6d5a6{STARTING}[11.0.22-SNAPSHOT,sto=5000] @1463ms
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-06-21 15:33:59.993:INFO :oejs.Server:main: jetty-11.0.22-SNAPSHOT; built: 2024-06-21T15:28:57.563Z; git: 3ec84034a62c56b0b42f1c85d5eee44f8c2e9136; jvm 22.0.1+8
2024-06-21 15:34:00.073:INFO :oejs.AbstractConnector:main: Started ServerConnector@dbf57b3{HTTP/1.1, (http/1.1)}{0.0.0.0:9999}
2024-06-21 15:34:00.103:INFO :oejs.Server:main: Started Server@56a6d5a6{STARTING}[11.0.22-SNAPSHOT,sto=5000] @1684ms
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
*.warfiles 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-06-21 15:34:04.485:INFO :oejs.Server:main: jetty-11.0.22-SNAPSHOT; built: 2024-06-21T15:28:57.563Z; git: 3ec84034a62c56b0b42f1c85d5eee44f8c2e9136; jvm 22.0.1+8
2024-06-21 15:34:04.540:INFO :oejdp.ScanningAppProvider:main: Deployment monitor [file:///path/to/jetty.home-base/webapps/]
2024-06-21 15:34:04.729:INFO :oejw.StandardDescriptorProcessor:main: NO JSP Support for /demo-simple, did not find org.eclipse.jetty.jsp.JettyJspServlet
2024-06-21 15:34:04.748:INFO :oejss.DefaultSessionIdManager:main: Session workerName=node0
2024-06-21 15:34:04.790:INFO :oejsh.ContextHandler:main: Started o.e.j.w.WebAppContext@693fe6c9{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-06-21 15:34:04.802:INFO :oejs.AbstractConnector:main: Started ServerConnector@6d60fe40{HTTP/1.1, (http/1.1)}{0.0.0.0:8080}
2024-06-21 15:34:04.828:INFO :oejs.Server:main: Started Server@6150c3ec{STARTING}[11.0.22-SNAPSHOT,sto=5000] @1788ms
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.