You can make Jetty aware of web applications to deploy in two ways:
By placing the web application in a specific location. For Jetty version 7.0.2 and later, the
WebAppProvider
of the
DeploymentManager
controls location-based web app deployment.
By creating a file that describes the deployment properties of your web application. For Jetty version
7.0.2 and later, the
ContextProvider
of the
DeploymentManager
controls contexts deployment.
In either case the web application may be either packed or unpacked WAR files.
Before discussing the mechanisms for deploying Jetty applications, it is helpful to define two terms:
Context –the name for a deployed instance of a web application. A web application is to a context as a class is to an object of that class type.
Context Path –the URL that identifies a particular context. Jetty uses it to route requests to the appropriate context.
In a default installation, Jetty scans its $JETTY_HOME/webapps
directory at startup for
web applications to deploy. To deploy your web application, simply place it in that directory.
Once it detects the web application, Jetty deploys it in the following manner:
It deploys the file foo.war
as a webapp at context /foo
.
It deploys the directory foo/
at context /foo
. If the directory
has a WEB-INF
subdirectory, Jetty treats it as a servlet webapp, otherwise Jetty serves it
only as static content.
If both a foo.war
and a foo/
directory exist, Jetty uses the
one with the most recent last-modified date.
If the webapp is called root.war
or the directory is called
root/
, Jetty deploys it at the / context.
If the contextXmlDir
option is used and a foo.xml
file exists
in that directory, the WebAppProvider
defers to the ContextProvider
for actual webapp
deployment.
Using the location based deployment model is quick and easy, but sometimes you might need to tune certain deployment properties (for example, you want to deploy with a context path that is not based on the file name, or you want to define a special database connection pool just for this web application). You can use a context deployment descriptor file to accomplish such tuning.
In a default Jetty installation, Jetty scans its $JETTY_HOME/contexts
directory for
context deployment descriptor files. To deploy a web application using such a file, simply place the file in that
directory.
The deployment descriptor file itself is a standard Jetty [[Jetty/Reference/jetty.xml
syntax|configuration]] //TODO Xref// file that configures a
WebAppContext
class. For a basic installation you probably need to set only two properties:
war –the filesystem path to the web application file/directory.
contextPath –the context path to use for the web application.
For example, here is a descriptor file that deploys the file /opt/myapp/myapp.war
to
the context path /wiki
:
<?xml version="1.0" encoding="ISO-8859-1"?> <!DOCTYPE Configure PUBLIC "-//Jetty//Configure//EN" "http://www.eclipse.org/jetty/configure.dtd"> <Configure class="org.eclipse.jetty.webapp.WebAppContext"> <Set name="contextPath">/wiki</Set> <Set name="war">/opt/myapp/myapp.war</Set> </Configure>
You can use the SystemProperty
and Property
elements in your descriptor file.
For example, if you set the system property myapp.home=/opt/myapp
, you can rewrite the previous
example as:
<?xml version="1.0" encoding="ISO-8859-1"?> <!DOCTYPE Configure PUBLIC "-//Jetty//Configure//EN" "http://www.eclipse.org/jetty/configure.dtd"> <Configure class="org.eclipse.jetty.webapp.WebAppContext"> <Set name="contextPath">/wiki</Set> <Set name="war"><SystemProperty name="myapp.home"/>/myapp.war</Set> </Configure>
If you need to change the home path for your application, you can simply change the system property. This is useful if you frequently switch among multiple versions of an app.
If you look at the documentation for the
WebAppContext
class, you notice that there are a lot more properties than just the two mentioned above. Here are some
examples that configure advanced optons with your descriptor file.
This first example tells Jetty not to expand the WAR file when deploying it. This can help make it clear that people should not be making changes to the temporary unpacked WAR because such changes do not persist, and therefore do not apply the next time the web application deploys.
<?xml version="1.0" encoding="ISO-8859-1"?> <!DOCTYPE Configure PUBLIC "-//Jetty//Configure//EN" "http://www.eclipse.org/jetty/configure.dtd"> <Configure class="org.eclipse.jetty.webapp.WebAppContext"> <Set name="contextPath">/wiki</Set> <Set name="war"><SystemProperty name="myapp.home"/>/myapp.war</Set> <Set name="extractWAR">false</Set> </Configure>
The next example retrieves the JavaEE Servlet context and sets an initialization parameter on it. You can
also use the setAttribute
method to set a Servlet context attribute. However, since the
web.xml
for the web application is processed after the deployment descriptor, the
web.xml
values overwrite like-named attributes from the deployment descriptor.
<?xml version="1.0" encoding="ISO-8859-1"?> <!DOCTYPE Configure PUBLIC "-//Jetty//Configure//EN" "http://www.eclipse.org/jetty/configure.dtd"> <Configure class="org.eclipse.jetty.webapp.WebAppContext"> <Set name="contextPath">/wiki</Set> <Set name="war"><SystemProperty name="myapp.home"/>/myapp.war</Set> <Get name="ServletContext"> <Call name="setInitParameter"> <Arg>myapp.config</Arg> <Arg><SystemProperty name="myapp.home">/config/app-config.xml</Arg> </Call> </Get> </Configure>
The following example sets a special web.xml
override descriptor. This descriptor is
processed after the web application's web.xml
, so may override like-named attributes. This
feature is useful if you want to add parameters or additional Servlet mappings without breaking open a packed WAR
file.
<?xml version="1.0" encoding="ISO-8859-1"?> <!DOCTYPE Configure PUBLIC "-//Jetty//Configure//EN" "http://www.eclipse.org/jetty/configure.dtd"> <Configure class="org.eclipse.jetty.webapp.WebAppContext"> <Set name="contextPath">/wiki</Set> <Set name="war"><SystemProperty name="myapp.home"/>/myapp.war</Set> <Set name="overrideDescriptor">/opt/myapp/overlay-web.xml</Set> </Configure>
The next example configures not only the web application context, but also a database connection pool (see
??? that our application can then use. If the
web.xml
does not include a reference to this data source, you can use the override descriptor
mechanism (the previous example), to include it.
<?xml version="1.0" encoding="ISO-8859-1"?> <!DOCTYPE Configure PUBLIC "-//Jetty//Configure//EN" "http://www.eclipse.org/jetty/configure.dtd"> <Configure class="org.eclipse.jetty.webapp.WebAppContext"> <Set name="contextPath">/wiki</Set> <Set name="war"><SystemProperty name="myapp.home"/>/myapp.war</Set> </Configure> <New id="DSTest" class="org.eclipse.jetty.plus.jndi.Resource"> <Arg></Arg> <Arg>jdbc/DSTest</Arg> <Arg> <New class="org.apache.commons.dbcp.BasicDataSource"> <Set name="driverClassName">org.some.Driver</Set> <Set name="url">jdbc.url</Set> <Set name="username">jdbc.user</Set> <Set name="password">jdbc.pass</Set> </New> </Arg> </New>
If you develop your web application as a Maven project, you can deploy it in Jetty with mvn
jetty:run
, using the Configuring the Jetty Maven Plugin.
Maven lets you build your web applications by overlaying on other template web applications (for example,
CometD) and manages the transitive dependencies
needed to populate WEB-INF/lib
.
You can also deploy web applications into embedded Jetty, either via direct configuration or via configuration of a deployer. For an example see ???.