Starting up Jetty

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:

java -jar start.jar

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

Value

jetty.home

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

jetty.host

host for the default connector. No default value.

jetty.port

port for the default connector. Default value is 8080.

jetty.logs

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

To use these, do

java -Doption1=value -Doption2=value -jar start.jar etc/jetty.xml

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.

Overview

Configuration file

A server configuration file will look something like this:

<?xml version="1.0"?>
<!DOCTYPE Configure PUBLIC "-//Mort Bay Consulting//DTD Configure//EN" "http://jetty.mortbay.org/configure.dtd">

<Configure id="Server" class="org.mortbay.jetty.Server">

  <!-- required configuration -->
  <!-- connectors -->
  <!-- handlers -->
  <!-- webapps/contexts -->

  <!-- optional configuration -->
  <!-- threadpool -->
  <!-- session id manager -->
  <!-- authentication realms -->
  <!-- request logs -->
  <!-- extra server options -->
</Configure>

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 .

<!DOCTYPE Configure PUBLIC "-//Mort Bay Consulting//DTD Configure//EN" "http://jetty.mortbay.org/configure.dtd">

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.

<Configure id="Server" class="org.mortbay.jetty.Server">
   ...
</Configure>

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.

<Set name="connectors">
  <Array type="org.mortbay.jetty.Connector">
    <Item>
      <New class="org.mortbay.jetty.nio.SelectChannelConnector">
        <Set name="host"><SystemProperty name="jetty.host" /></Set>
        <Set name="port"><SystemProperty name="jetty.port" default="8080"/></Set>
        ...
      </New>
    </Item>
  </Array>
</Set>

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:

<Set name="handlers">
  <Array type="org.mortbay.jetty.Handler">
   ...
</Set>

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:

<Set name="ThreadPool">
 <New class="org.mortbay.thread.QueuedThreadPool">
    <Set name="minThreads">10</Set>
    <Set name="maxThreads">200</Set>
    <Set name="lowThreads">20</Set>
    <Set name="SpawnOrShrinkAt">2</Set>
 </New>
</Set>

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/realm.properties file:

<Set name="UserRealms">
  <Array type="org.mortbay.jetty.security.UserRealm">
   <Item>
    <New class="org.mortbay.jetty.security.HashUserRealm">
     <Set name="name">Test Realm</Set>
     <Set name="config">etc/realm.properties</Set>
    </New>
   </Item>
  </Array>
</Set>

More

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

Examples

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:

<?xml version="1.0"?>
<!DOCTYPE Configure PUBLIC "-//Mort Bay Consulting//DTD Configure//EN" "http://jetty.mortbay.org/configure.dtd">

<Configure id="Server" class="org.mortbay.jetty.Server">
    <Call name="addConnector">
      <Arg>
          <New class="org.mortbay.jetty.nio.SelectChannelConnector">
            <Set name="port">8080</Set>
          </New>
      </Arg>
    </Call>

    <Set name="handler">
      <New id="Handlers" class="org.mortbay.jetty.handler.HandlerCollection">
        <Set name="handlers">
          <Array type="org.mortbay.jetty.Handler">
            <Item>
              <New id="Contexts" class="org.mortbay.jetty.handler.ContextHandlerCollection"/>
            </Item>
          </Array>
        </Set>
      </New>
    </Set>

    <Call name="addLifeCycle">
      <Arg>
        <New class="org.mortbay.jetty.deployer.WebAppDeployer">
          <Set name="contexts"><Ref id="Contexts"/></Set>
          <Set name="webAppDir"><SystemProperty name="jetty.home" default="."/>/webapps</Set>
        </New>
      </Arg>
    </Call>
</Configure>

Start up Jetty with this command:

java -jar start.jar etc/myjetty.xml

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:

<?xml version="1.0"?>
<!DOCTYPE Configure PUBLIC "-//Mort Bay Consulting//DTD Configure//EN" "http://jetty.mortbay.org/configure.dtd">

<Configure id="Server" class="org.mortbay.jetty.Server">
    <Call name="addConnector">
      <Arg>
          <New class="org.mortbay.jetty.nio.SelectChannelConnector">
            <Set name="host"><SystemProperty name="jetty.host" /></Set>
            <Set name="port"><SystemProperty name="jetty.port" default="8080"/></Set>
          </New>
      </Arg>
    </Call>

    <Set name="handler">
      <New id="Handlers" class="org.mortbay.jetty.handler.HandlerCollection">
        <Set name="handlers">
         <Array type="org.mortbay.jetty.Handler">
           <Item>
             <New id="Contexts" class="org.mortbay.jetty.handler.ContextHandlerCollection"/>
           </Item>
           <Item>
             <New id="DefaultHandler" class="org.mortbay.jetty.handler.DefaultHandler"/>
           </Item>
         </Array>
        </Set>
      </New>
    </Set>

    <Call name="addLifeCycle">
      <Arg>
        <New class="org.mortbay.jetty.deployer.WebAppDeployer">
          <Set name="contexts"><Ref id="Contexts"/></Set>
          <Set name="webAppDir"><SystemProperty name="jetty.home" default="."/>/webapps</Set>
    	  <Set name="parentLoaderPriority">false</Set>
    	  <Set name="extract">true</Set>
    	  <Set name="allowDuplicates">false</Set>
          <Set name="defaultsDescriptor"><SystemProperty name="jetty.home" default="."/>/etc/webdefault.xml</Set>
        </New>
      </Arg>
    </Call>
</Configure>

As before, start up Jetty with this command:

java -jar start.jar etc/myjetty.xml

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:

    <Call name="addLifeCycle">
      <Arg>
        <New class="org.mortbay.jetty.deployer.ContextDeployer">
          <Set name="contexts"><Ref id="Contexts"/></Set>
          <Set name="configurationDir"><SystemProperty name="jetty.home" default="."/>/contexts</Set>
          <Set name="scanInterval">5</Set>
        </New>
      </Arg>
    </Call>

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:

<?xml version="1.0"?>
<!DOCTYPE Configure PUBLIC "-//Mort Bay Consulting//DTD Configure//EN" "http://jetty.mortbay.org/configure.dtd">

<Configure id="Server" class="org.mortbay.jetty.Server">
    <Call name="addConnector">
      <Arg>
          <New class="org.mortbay.jetty.nio.SelectChannelConnector">
            <Set name="port"><SystemProperty name="jetty.port" default="8080"/></Set>
          </New>
      </Arg>
    </Call>
    <Set name="handler">
        <New id="ResourceHandler" class="org.mortbay.jetty.handler.ResourceHandler">
            <Set name="resourceBase">.</Set>
        </New>
    </Set>
</Configure>

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

<?xml version="1.0"?>
<!DOCTYPE Configure PUBLIC "-//Mort Bay Consulting//DTD Configure//EN" "http://jetty.mortbay.org/configure.dtd">

<Configure id="Server" class="org.mortbay.jetty.Server">
    <Call name="addConnector">
      <Arg>
          <New class="org.mortbay.jetty.nio.SelectChannelConnector">
            <Set name="port"><SystemProperty name="jetty.port" default="8080"/></Set>
          </New>
      </Arg>
    </Call>
    <Set name="handler">
      <New id="Handlers" class="org.mortbay.jetty.handler.HandlerCollection">
        <Set name="handlers">
         <Array type="org.mortbay.jetty.Handler">
           <Item>
             <New id="ResourceHandler" class="org.mortbay.jetty.handler.ResourceHandler">
               <Set name="resourceBase">./logs</Set>
             </New>
           </Item>
           <Item>
            <New id="RequestLog" class="org.mortbay.jetty.handler.RequestLogHandler"/>
           </Item>
         </Array>
        </Set>
      </New>
    </Set>

    <Ref id="RequestLog">
      <Set name="requestLog">
        <New id="RequestLogImpl" class="org.mortbay.jetty.NCSARequestLog">
          <Set name="filename"><SystemProperty name="jetty.logs" default="./logs"/>/request.log</Set>
          <Set name="append">false</Set>
        </New>
      </Set>
    </Ref>
</Configure>

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.