Jetty has moved!
Jetty is a project at the Eclipse Foundation.
Jetty Powered:
Contact the core Jetty developers at
private support for your internal/customer projects ... custom extensions and distributions ... versioned snapshots for indefinite support ... scalability guidance for your apps and Ajax/Comet projects ... development services from 1 day to full product delivery
Skip to end of metadata
Go to start of metadata

Starting up Jetty

  • jetty-runner.jar - fast and easy way to run your webapp, without needing to install and administer a jetty distro. Run it using java -jar jetty-runner.jar webappcontext. Further instructions can be found in the blog entry linked to above.
  • start.jar - start from within your Jetty installation. Run it using java -jar start.jar configuration files
  • embed Jetty into your application
  • as a distribution package (RPM, .deb)
  • Maven Jetty Plugin

Starting with Jetty using start.jar and jetty.xml

These instructions assume that you have installed Jetty, although the configuration examples provided are applicable to anywhere you pass in a jetty.xml file.

etc/jetty.xml is the default configuration file for Jetty. It demonstrates several basic functions, and can be used as the basis for your own configuration. To immediately start up Jetty and begin looking around, go to $JETTY_HOME and run this command:

That starts up Jetty and applies the configuration specified in etc/jetty.xml. You can then view the page by visiting http://localhost:8080/.

There are several additional options that can be set on the command line when using the supplied jetty.xml:

Option name



directory which contains the etc, webapps, contexts folders. No trailing slash. Default value is the directory from which you are running start.jar.

host for the default connector. No default value.


port for the default connector. Default value is 8080.


directory which contains the request logs. No trailing slash. Default value is ${jetty.home}/logs

To use these, do

More information about starting and stopping Jetty can be found in Running Jetty-6.1.x.

Customizing your Jetty configuration

etc/jetty.xml sets reasonable defaults, but you will want to customize Jetty to fit your needs. This section takes you through configuring Jetty using an XML file. Most examples will be based from the jetty.xml file, but there are also additional examples for several common use cases.


Configuration file

A server configuration file will look something like this:

Configuration file breakdown

Doctype (required)

All tags and elements declared inside jetty.xml will be pointing to this resource, configure.dtd. This means that only tags and elements based from this data type file will be valid .

Server (required)

org.mortbay.jetty.Server is the main class for the Jetty HTTP server. It is the first instance called when you run the server. It aggregates Connectors (HTTP request receivers) and request Handlers. The server is itself a handler and a ThreadPool. Connectors use the ThreadPool methods to run jobs that will eventually call the handle method.

Connectors (required)

Implementations of the org.mortbay.jetty.Connector interface provide connectors for the HTTP protocol. It is here that you set the ports that Jetty will listen on for incoming connections.

Handlers (required)

Handlers process inbound requests. There is a handler which services web applications called org.mortbay.jetty.webapp.WebAppContext. If you don't wish to use a full-blown application but just want to serve static content and maybe some servlets, then you can use a ContextHandler and only configure those services you require. The list of handlers that are defined for a Server is set by the following call:

ThreadPool (optional)

The ThreadPool class avoids the expense of thread creation by pooling threads for reuse after their run methods exit. If the maximum pool size is reached, jobs wait for a free thread. By default there is no maximum pool size. Idle threads timeout and terminate until the minimum number of threads are running. Configuring the ThreadPool is optional, because the server falls back upon defaults. However, you may wish to customize the thread pool to better fit your application. Example:

Security Realm (optional)

If you want to use authentication and authorisation, then you need to define a Security realm. There is no limit to the number or types of realms that you can define for a Server. The following example sets up a security realm that is populated by the etc/ file:


For a more detailed explanation of the default settings, see the jetty.xml walkthrough. The Syntax Reference explains the syntax for individual elements.


All examples assume that you are in $JETTY_HOME, and that the configuration file below is saved under $JETTY_HOME/etc/myjetty.xml.

Barebones Static Webapp Deployment

Below is the bare minimum required to start up the Jetty server and start serving up standard web applications. This will listen for connections on port 8080, and serve up any webapps placed under the $JETTY_HOME/webapps folder:

Start up Jetty with this command:

View your webapplications at http://localhost:8080/webappfolder/. If you have no webapp defined for the root context ("/"), visiting http://localhost:8080/ will give you a normal 404 page.

Static Webapp Deployment, version 2

Here is a slightly more advanced version of the above:

As before, start up Jetty with this command:

View your webapplications at http://localhost:8080/webappfolder/.

Other than the extra configuration settings, the biggest change is the addition of the org.mortbay.jetty.handler.DefaultHandler, which deals with unhandled requests in the server. If you have no webapps defined in the root context ("/"), visiting http://localhost:8080/ will 404, but will present a list of contexts that have been deployed on the server. DefaultHandler also serves up a Jetty favicon.

For more details about configuring static deployment, see WebAppDeployer.

Hot Deployment of Customized Contexts

In addition to deploying webapps at start-up, you can also do hot deployment: configure a context deployer which scans a specific directory for XML configuration files, and deploys/redeploys/undeploys a webapp if its configuration file has been modified, added, or removed. These configuration files also allow you to configure certain Jetty-specific per-context settings; configuration file and its format is specific to Jetty. To keep things short, I am not going to reproduce the entire configuration. Add this block to either of the previous examples:

That sets up a ContextDeployer, which will scan the $JETTY_HOME/contexts folder every 5 seconds for changes to the XML descriptors, and hot deploy as necessary. For more details, see ContextDeployer.

File Server, One Handler

Simple HTTP file server with one handler, similar to the embedded FileServer example and embedded OneHandler example. This example serves up purely static files from your current directory:

Note that ResourceHandler does not allow directory listing; if you visit a directory with no welcome files, you will get a 403 Forbidden error message. Try the exact path to the file.

If you just want a specific context to serve static content, while still serving dynamic web applications from other contexts, configure your server to allow hot deployment (see previous example), then set up a context to serve up Static Content.

File Server, Multiple Handlers

Simple HTTP file server with request logging. Similar to the embedded FileServer example and embedded ManyHandlers example

Similar to the one handler example, but defines multiple handlers. A handler can be configured either as soon as it is declared, or further down using the Ref tag. There is no difference in effect between the two. That example serves up static files in the logs directory under your current directory, and logs all requests since the server was last started to request.log.

To see this in action, go to http://localhost:8080/request.log and refresh a few times (you may need to hard refresh, to make sure you are not seeing a cached copy of the data).

For simplicity's sake, the logfile's name does not contain a date; see jetty.xml for an extended configuration which does.

Either a HandlerCollection or a HandlerList can be used when setting multiple handlers. org.mortbay.jetty.handler.HandlerCollection calls all handlers in turn. org.mortbay.jetty.handler.HandlerList calls each contained handler until either an exception is thrown, the response is committed,or a positive response status is sent. In this case, HandlerCollection was chosen so that the RequestLogHandler could log the requests.

  • No labels
Contact the core Jetty developers at
private support for your internal/customer projects ... custom extensions and distributions ... versioned snapshots for indefinite support ... scalability guidance for your apps and Ajax/Comet projects ... development services from 1 day to full product delivery