Contact the core Jetty developers at www.webtide.com
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

Running Jetty

Starting Jetty
Deploying Web Applications
Stopping Jetty

Starting Jetty

To start the jetty distribution on the default port of 8080 run the following command:

> java -jar start.jar

If everything goes correctly you should see about 20 lines of logged INFO statements that will include lines like the following, that inform you of the components being started:

2012-10-22 16:02:24.988:INFO:oejs.Server:main: jetty-9.0.0-M2 2012-10-22
      16:02:25.040:INFO:oejs.NCSARequestLog:main: Opened
      /home/gregw/src/jetty-9/jetty-distribution/target/distribution/logs/2012_10_22.request.log 2012-10-22
      16:02:25.115:INFO:oejs.ServerConnector:main: Started ServerConnector@6aeeafb{HTTP/1.1}{0.0.0.0:8080} 2012-10-22
      16:02:25.348:INFO:oejs.ServerConnector:main: Started ServerConnector@24a45e{SSL-http/1.1}{0.0.0.0:8443}
      2012-10-22 16:02:25.357:INFO:oejdp.ScanningAppProvider:main: Deployment monitor
      [file:/home/gregw/src/jetty-9/jetty-distribution/target/distribution/webapps/] at interval 1 2012-10-22
      16:02:25.688:INFO:oejd.DeploymentManager:main: Deployable added:
      /home/gregw/src/jetty-9/jetty-distribution/target/distribution/webapps/test.xml 2012-10-22
      16:02:25.725:INFO:oejw.WebInfConfiguration:main: Extract
      jar:file:/home/gregw/src/jetty-9/jetty-distribution/target/distribution/webapps/test.war!/ to
      /tmp/jetty-0.0.0.0-8080-test.war-_test-any-/webapp 2012-10-22 16:02:26.097:INFO:oejsh.ContextHandler:main:
      started
      o.e.j.w.WebAppContext@4e3ceb07{/test,file:/tmp/jetty-0.0.0.0-8080-test.war-_test-any-/webapp/,AVAILABLE}{/test.war}

You will also see some warnings like:

2012-10-22 16:02:24.748:WARN::main: test-realm is deployed. DO NOT USE IN
      PRODUCTION! 2012-10-22 16:02:25.582:WARN::main: async-rest webapp is deployed. DO NOT USE IN
      PRODUCTION!

These warnings are telling you that some demonstration web applications and services are deployed and that they should be removed before the server is put into production. These warnings can be ignored while testing, or you can see Deploying Web Applications to learn how to remove them.

You can test the started Jetty by pointing a Browser or any HTTP client at port 8080 of the machine. If you are running the browser on the same machine as the Jetty instance, then the URL to use is:

http://localhost:8080/

Your browser or HTTP client should see the Jetty welcome page and be able to follow the links to some test web applications.

Changing the Jetty Port

If you see the following exception you already have something running on the port that jetty is configured to run on and you either need to shut down whatever that process is, or configure jetty to run on another port.

java.net.BindException: Address already in use at sun.nio.ch.Net.bind0(Native
        Method) at sun.nio.ch.Net.bind(Net.java:344) at sun.nio.ch.Net.bind(Net.java:336) at
        sun.nio.ch.ServerSocketChannelImpl.bind(ServerSocketChannelImpl.java:199)

Jetty can be made to run on a different port by adding setting the jetty.port Property on the command line:

> java -jar start.jar jetty.port=8081

This property can also be set in the start.ini file or by editing the usage of the property in the etc/jetty-http.xml configuration file. For more information see Chapter 4, Configuring Jetty Connectors.

Starting HTTPS

By defaults set in the start.ini file, Jetty starts the HTTP connector that is defined in etc/jetty-http.xml. To also start the HTTPS connector defined in etc/jetty-https.xml you can simply append this configuration file to the command line:

> java -jar start.jar etc/jetty-https.xml

You can now test this connector by pointing your browser to:

https://localhost:8443/

Alternately you can edit the start.ini file and uncomment the line that includes the https configuration file and then start jetty without any extra command line arguments. Note also that the SSL port can be changed with the jetty.tls.port Property:

> java -jar start.jar jetty.tls.port=8444 etc/jetty-https.xml

The job of the start.jar command is to interpret the command line and start.ini arguments in order to build a java classpath and list of properties and configuration files to pass to the main class of the Jetty XML configuration mechanism. The start.jar mechanism has many options which are documented in Chapter 14, Starting Jettyand can be seen in summary with the command:

> java -jar start.jar --help

Deploying Web Applications

Jetty by default includes the etc/jetty-deploy.xml file in start.ini, which configures a web application Deployer that hot deploys files found in the webapps directory. Standard WAR files and jetty configuration files that are placed in the webapps directory will be hot deployed to the server with the following conventions:

  • A directory called example/ will be deployed as a standard web application if it contains a WEB-INF/ subdirectory, otherwise it will be deployed as context of static content. The context path will be /example (eg http://localhost:8080/example/) unless the base name is root, in which case the context path is /. If the directory name ends with ".d" it is ignored (by may be used by explicit configuration).

  • A file called example.war will be deployed as a standard web application with the context path /example (eg http://localhost:8080/example/). If he base name is root, then the context path is /. If example.war and example/ exist, then only the WAR is deployed (which may use the directory as an unpack location).

  • An XML file like example.xml will be deployed as a context whose configuration is defined by the XML. The context path must be set by the configuration itself. If example.xml and example.war exist, then only the XML is deployed (which may use the war in its configuration).

If you have a standard web application, it can hot deployed into jetty by copying it into the webapps directory. Alternately to test deployment you can copy the provided test web application provided:

> cp webapps/test.war webapps/myapp.war

The Jetty distribution comes with the following deployed in the webapps directory:

ROOT/

The Jetty welcome page served as static content.

test.xml

The configuration file that deploys the demonstration web application in test.war using the extra configuration contained within test.d

test.war

The demonstration web application that is configured and deployed by test.xml

test.d

A directory containing additional configuration files used by test.xml

async-rest.war

A web application demonstration asynchronous REST to Ebay.

javadoc.xml

A context configuration that deploys as static content the javadoc directory found at jetty.home/javadoc

These demonstration web applications should be removed before using Jetty in production.

Stopping Jetty

If jetty has been simply started from the command line, then it is safe to stop it using the normal Ctrl-C key sequence to abort it. This will trigger an orderly shutdown of the server.

However, the server may be started with some advanced start.jar options so that it runs in the background:

> java -jar start.jar STOP.PORT=8881 STOP.KEY=magic --daemon &

This server may now be shutdown with the command:

> java -jar start.jar STOP.PORT=8881 STOP.KEY=magic --stop

See an error or something missing?
Contribute to this documentation at Github!