Jetty Logo
Version: 9.2.2-SNAPSHOT
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

Chapter 19. Jetty Runner

Table of Contents

Use Jetty without an installed distribution

This chapter explains how to use the jetty-runner to run your webapps without needing an installation of jetty.

Use Jetty without an installed distribution

The idea of the jetty-runner is extremely simple – run a webapp directly from the command line using a single jar and as much default configuration as possible. Of course, if your webapp is not so straightforward, the jetty-runner has command line options which allow you to customize the execution environment.

Preparation

You will need the jetty-runner jar:

  1. Get the jetty-runner jar, from maven central

Deploying a simple context

Let's assume we have a very simple webapp, that does not need any resources from its environment, nor any configuration apart from the defaults. Starting it is as simple as doing the following:


> java -jar jetty-runner.jar simple.war

      

This will start jetty on port 8080, and deploy the webapp to "/".

Your webapp does not have to be packed into a war, you can deploy a webapp that is a directory instead in the same way:


> java -jar jetty-runner.jar simple

      

In fact, the webapp does not have to be a war or even a directory, it can simply be a jetty context xml file that describes your webapp:


> java -jar jetty-runner.jar simple-context.xml

      

Note

When using a context xml file, the application being deployed is not even required to be a fully-fledged webapp. It can simply be a Jetty context.

Deploying multiple contexts

If you have more than one webapp that must be deployed, simply provide them all on the command line. You can control the context paths for them using the "--path" parameter. Here's an example of deploying 2 wars (although either or both of them could be unpacked directories instead):


> java -jar jetty-runner.jar --path /one my1.war --path /two my2.war

      

If you have context xml files that describe your webapps, you can fully configure your webapps in them, and hence you don't need to use the command line switches. Just provide the list of context files like so:


> java -jar jetty-runner.jar my-first-context.xml my-second-context.xml my-third-context.xml

      

Note

The command line switches override configuration file settings. So, for example, you could set the context path for the webapp inside the context xml file, and use the --path switch to override it on the command line.

Changing the default port

By default the jetty-runner will listen on port 8080. You can easily change this on the command line using the "--port" command. Here's an example that runs our simple.war on port 9090:


> java -jar jetty-runner.jar --port 9090 simple.war

      

Using jetty.xml files

Instead of, or in addition to using command line switches, you can use one or more jetty.xml files to configure the environment for your webapps. Here's an example where we apply two different jetty.xml files:


> java -jar jetty-runner.jar --config jetty.xml --config jetty-https.xml simple.war

      

Note

Switches on the command line take precendence over those defined in configuration files, so you can use the command line as overrides.

Full configuration reference

You can see the fill set of configuration options using the --help switch:


> java -jar jetty-runner.jar --help

      

Here's what the output will look like:

Printing the version:

Print out the version of jetty and then exit immediately.


> java -jar jetty-runner.jar --version

          
Configuring a request log:

Cause jetty to write a request log with the given name. If the file is prefixed with yyyy_mm_dd then the file will be automatically rolled over. Note that for finer grained configuration of the request log, you will need to use a jetty xml file instead.


> java -jar jetty-runner.jar --log yyyy_mm_dd-requests.log  my.war

            
Configuring the output log:

Redirect the output of jetty logging to the named file. If the file is prefixed with yyyy_mm_dd then the file will be automatically rolled over.


> java -jar jetty-runner.jar --out yyyy_mm_dd-output.log my.war

            
Configuring the interface for http:

Like jetty standalone, the default is for the connectors to listen on all interfaces on a machine. You can control that by specifying the name or ip address of the particular interface you wish to use with the --host argument:

> java -jar jetty-runner.jar --host 192.168.22.19 my.war
Configuring the port for http:

The default port number is 8080. To configure a https connector, use a jetty xml config file instead.


> java -jar jetty-runner.jar --port 9090  my.war

            
Configuring stop:

You can configure a port number for jetty to listen on for a stop command, so you are able to stop it from a different terminal. This requires the use of a "secret" key, to prevent malicious or accidental termination. Use the --stop-port and --stop-key parameters as arguments to the jetty-runner:


> java -jar jetty-runner.jar --stop-port 8181 --stop-key abc123

            

Then, to stop jetty from a different terminal, you need to supply the same port and key information. For this you'll either need a local installation of jetty, the jetty-maven-plugin, the jetty-ant plugin, or write a custom class. Here's how to use a jetty installation to perform a stop:


> java -jar start.jar --stop-port 8181 --stop-key abc123 --stop

            
Configuring the container classpath:

With a local installation of jetty, you add jars and classes to the container's classpath by putting them in the $JETTY_HOME/lib directory. With the jetty-runner, you can use the --lib, --jar and --classes arguments instead to achieve the same thing.

--lib adds the location of a directory which contains jars to add to the container classpath. You can add 1 or more. Here's an example of configuring 2 directories:


> java -jar jetty-runner.jar --lib /usr/local/external/lib --lib $HOME/external-other/lib my.war

            

--jar adds a single jar file to the container classpath. You can add 1 or more. Here's an example of configuring 3 extra jars:


> java -jar jetty-runner.jar --jar /opt/stuff/jars/jar1.jar --jar $HOME/jars/jar2.jar --jar /usr/local/proj/jars/jar3.jar  my.war

            

--classes add the location of a directory containing classes to add to the container classpath. You can add 1 or more. Here's an example of configuring a single extra classes dir:


> java -jar jetty-runner.jar --classes /opt/stuff/classes my.war

            
Gathering statistics:

If statistics gathering is enabled, then they are viewable by surfing to the context /stats. You may optionally protect acess to that context with a password. Here's an example of enabling statistics, with no password protection:


> java -jar jetty-runner.jar --stats unsecure my.war

            

If we wished to protect acess to the /stats context, we would provide the location of a jetty realm configuration file containing authentication and authorization information. For example, we could use the following example realm file from the jetty distribution:

Assuming we've copied it into the local directory, we would apply it like so


> java -jar jetty-runner.jar --stats realm.properties my.war

            

After surfing to http://localhost:8080/ a few times, we can surf to the stats servlet on http://localhost:8080/stats to see the output:

See an error or something missing? Contribute to this documentation at Github!(Generated: 2014-10-01T01:00:29-07:00)