<html><head>
      <meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1">
   <title>Configuring a Specific Web Application Deployment</title><link rel="stylesheet" type="text/css" href="css/docbook.css"><meta name="generator" content="DocBook XSL Stylesheets V1.79.1"><meta name="keywords" content="jetty, servlet, servlet-api, cometd, http, websocket, eclipse, maven, java, server, software"><link rel="home" href="index.html" title="Jetty"><link rel="up" href="configuring-deployment.html" title="Chapter&nbsp;4.&nbsp;Deploying to Jetty"><link rel="prev" href="automatic-webapp-deployment.html" title="Automatic Web Application Deployment"><link rel="next" href="configuring-webapps.html" title="Deployment Processing of WebAppContexts"><link xmlns:jfetch="java:org.eclipse.jetty.xslt.tools.JavaSourceFetchExtension" xmlns:fetch="java:org.eclipse.jetty.xslt.tools.SourceFetchExtension" xmlns:d="http://docbook.org/ns/docbook" xmlns:l="http://docbook.sourceforge.net/xmlns/l10n/1.0" xmlns:xslthl="http://xslthl.sf.net" xmlns:gcse="http://www.google.com" xmlns:date="http://exslt.org/dates-and-times" rel="shortcut icon" href="images/favicon.ico"><link rel="stylesheet" href="css/highlighter/foundation.css"><script src="js/highlight.pack.js"></script><script>
      hljs.initHighlightingOnLoad();
    </script><link type="text/css" rel="stylesheet" href="css/font-awesome/font-awesome.min.css"></head><body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"><table xmlns:jfetch="java:org.eclipse.jetty.xslt.tools.JavaSourceFetchExtension" xmlns:fetch="java:org.eclipse.jetty.xslt.tools.SourceFetchExtension" xmlns:d="http://docbook.org/ns/docbook" xmlns:l="http://docbook.sourceforge.net/xmlns/l10n/1.0" xmlns:xslthl="http://xslthl.sf.net" xmlns:gcse="http://www.google.com" xmlns:date="http://exslt.org/dates-and-times"><tr><td style="width: 25%"><a href="http://www.eclipse.org/jetty"><img src="images/jetty-header-logo.png" alt="Jetty Logo"></a><br><span style="font-size: small">
            Version: 9.4.28-SNAPSHOT</span></td><td style="width: 50%"></td></tr></table><div xmlns:jfetch="java:org.eclipse.jetty.xslt.tools.JavaSourceFetchExtension" xmlns:fetch="java:org.eclipse.jetty.xslt.tools.SourceFetchExtension" xmlns:d="http://docbook.org/ns/docbook" xmlns:l="http://docbook.sourceforge.net/xmlns/l10n/1.0" xmlns:xslthl="http://xslthl.sf.net" xmlns:gcse="http://www.google.com" xmlns:date="http://exslt.org/dates-and-times" class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="3" align="center">Configuring a Specific Web Application Deployment</th></tr><tr><td width="20%" align="left"><a accesskey="p" href="automatic-webapp-deployment.html"><i class="fa fa-chevron-left" aria-hidden="true"></i> Previous</a>&nbsp;</td><th width="60%" align="center">Chapter&nbsp;4.&nbsp;Deploying to Jetty<br><a accesskey="p" href="index.html"><i class="fa fa-home" aria-hidden="true"></i> Home</a></th><td width="20%" align="right">&nbsp;<a accesskey="n" href="configuring-webapps.html">Next <i class="fa fa-chevron-right" aria-hidden="true"></i></a></td></tr></table><hr></div><div xmlns:jfetch="java:org.eclipse.jetty.xslt.tools.JavaSourceFetchExtension" xmlns:fetch="java:org.eclipse.jetty.xslt.tools.SourceFetchExtension" xmlns:d="http://docbook.org/ns/docbook" xmlns:l="http://docbook.sourceforge.net/xmlns/l10n/1.0" xmlns:xslthl="http://xslthl.sf.net" xmlns:gcse="http://www.google.com" xmlns:date="http://exslt.org/dates-and-times" class="jetty-callout"><h5 class="callout"><a href="http://www.webtide.com/">Contact the core Jetty developers at
          <span class="website">www.webtide.com</span></a></h5><p>
 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 for sponsored feature development
      </p></div><div class="section"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="configuring-specific-webapp-deployment"></a>Configuring a Specific Web Application Deployment</h2></div></div></div><div class="toc"><dl class="toc"><dt><span class="section"><a href="configuring-specific-webapp-deployment.html#deployable-descriptor-file">Jetty Deployable Descriptor XML File</a></span></dt><dt><span class="section"><a href="configuring-specific-webapp-deployment.html#using-basic-descriptor-files">Using Basic Descriptor Files</a></span></dt><dt><span class="section"><a href="configuring-specific-webapp-deployment.html#configuring-advanced-descriptor-files">Configuring Advanced Descriptor Files</a></span></dt></dl></div><p>Using the Automatic Web Application 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 <a class="xref" href="configuring-specific-webapp-deployment.html#deployable-descriptor-file" title="Jetty Deployable Descriptor XML File">Jetty Deployable Descriptor XML File</a> to accomplish such tuning.</p><div class="section"><div class="titlepage"><div><div><h3 class="title"><a name="deployable-descriptor-file"></a>Jetty Deployable Descriptor XML File</h3></div></div></div><p>Jetty supports deploying Web Applications via XML files which will build an instance of a <a class="link" href="http://www.eclipse.org/jetty/javadoc/9.4.28-SNAPSHOT/org/eclipse/jetty/server/handler/ContextHandler.html" target="_top">ContextHandler</a> that Jetty can then deploy.</p></div><div class="section"><div class="titlepage"><div><div><h3 class="title"><a name="using-basic-descriptor-files"></a>Using Basic Descriptor Files</h3></div></div></div><p>In a default Jetty installation, Jetty scans its <code class="literal">$JETTY_HOME/webapps</code> directory for context deployment descriptor files.
To deploy a web application using such a file, simply place the file in that directory.</p><p>The deployment descriptor file itself is an xml file that configures a <a class="link" href="http://www.eclipse.org/jetty/javadoc/9.4.28-SNAPSHOT/org/eclipse/jetty/webapp/WebAppContext.html" target="_top"><code class="literal">WebAppContext</code></a> class.
For a basic installation only two properties need configured:</p><div class="variablelist"><dl class="variablelist"><dt><span class="term">war</span></dt><dd>The filesystem path to the web application file (or directory)</dd><dt><span class="term">contextPath</span></dt><dd>The context path to use for the web application</dd></dl></div><p>For example, here is a descriptor file that deploys the file <code class="literal">/opt/myapp/myapp.war</code> to the context path <code class="literal">/wiki</code>:</p><pre xmlns:jfetch="java:org.eclipse.jetty.xslt.tools.JavaSourceFetchExtension" xmlns:fetch="java:org.eclipse.jetty.xslt.tools.SourceFetchExtension" xmlns:d="http://docbook.org/ns/docbook" xmlns:l="http://docbook.sourceforge.net/xmlns/l10n/1.0" xmlns:xslthl="http://xslthl.sf.net" xmlns:gcse="http://www.google.com" xmlns:date="http://exslt.org/dates-and-times"><code>&lt;?xml version="1.0" encoding="UTF-8"?&gt;
&lt;!DOCTYPE Configure PUBLIC "-//Jetty//Configure//EN" "http://www.eclipse.org/jetty/configure_9_3.dtd"&gt;

&lt;Configure class="org.eclipse.jetty.webapp.WebAppContext"&gt;
  &lt;Set name="contextPath"&gt;/wiki&lt;/Set&gt;
  &lt;Set name="war"&gt;/opt/myapp/myapp.war&lt;/Set&gt;
&lt;/Configure&gt;</code></pre><p>Both <code class="literal">SystemProperty</code> and <code class="literal">Property</code> elements can be used in the descriptor file.
For example, if the system property is set to <code class="literal">myapp.home=/opt/myapp</code>, the previous example can be rewritten as:</p><pre xmlns:jfetch="java:org.eclipse.jetty.xslt.tools.JavaSourceFetchExtension" xmlns:fetch="java:org.eclipse.jetty.xslt.tools.SourceFetchExtension" xmlns:d="http://docbook.org/ns/docbook" xmlns:l="http://docbook.sourceforge.net/xmlns/l10n/1.0" xmlns:xslthl="http://xslthl.sf.net" xmlns:gcse="http://www.google.com" xmlns:date="http://exslt.org/dates-and-times"><code>&lt;?xml version="1.0" encoding="UTF-8"?&gt;
&lt;!DOCTYPE Configure PUBLIC "-//Jetty//Configure//EN" "http://www.eclipse.org/jetty/configure_9_3.dtd"&gt;

&lt;Configure class="org.eclipse.jetty.webapp.WebAppContext"&gt;
  &lt;Set name="contextPath"&gt;/wiki&lt;/Set&gt;
  &lt;Set name="war"&gt;&lt;SystemProperty name="myapp.home"/&gt;/myapp.war&lt;/Set&gt;
&lt;/Configure&gt;</code></pre><p>If the home path for an application needs altered, only the system property needs changed.
This is useful if the version of an app is frequently changed.</p><div class="blockquote"><blockquote class="blockquote"><div xmlns:jfetch="java:org.eclipse.jetty.xslt.tools.JavaSourceFetchExtension" xmlns:fetch="java:org.eclipse.jetty.xslt.tools.SourceFetchExtension" xmlns:d="http://docbook.org/ns/docbook" xmlns:l="http://docbook.sourceforge.net/xmlns/l10n/1.0" xmlns:xslthl="http://xslthl.sf.net" xmlns:gcse="http://www.google.com" xmlns:date="http://exslt.org/dates-and-times" class="note" style="margin-left: 0.5in; margin-right: 0.5in;"><h3 class="title"><i class="fa fa-asterisk" aria-hidden="true"></i> Note</h3><p>To ensure your <code class="literal">web.xml</code> files are validated, you will need to set the <code class="literal">validateXml</code> attribute to true as described <a class="link" href="reference-section.html#jetty-xml-dtd" title="Understanding DTD and Parsing">here.</a></p></div></blockquote></div></div><div class="section"><div class="titlepage"><div><div><h3 class="title"><a name="configuring-advanced-descriptor-files"></a>Configuring Advanced Descriptor Files</h3></div></div></div><p>Official documentation for the for the <a class="link" href="http://www.eclipse.org/jetty/javadoc/9.4.28-SNAPSHOT/org/eclipse/jetty/webapp/WebAppContext.html" target="_top"><code class="literal">WebAppContext</code></a> class lists all the properties that can be set.
Here are some examples that configure advanced options in the descriptor file.</p><p>This first example tells Jetty not to expand the WAR file when deploying it.
This can help make it clear that users should not make changes to the temporary unpacked WAR because such changes do not persist, and therefore do not apply the next time the web application deploys.</p><pre xmlns:jfetch="java:org.eclipse.jetty.xslt.tools.JavaSourceFetchExtension" xmlns:fetch="java:org.eclipse.jetty.xslt.tools.SourceFetchExtension" xmlns:d="http://docbook.org/ns/docbook" xmlns:l="http://docbook.sourceforge.net/xmlns/l10n/1.0" xmlns:xslthl="http://xslthl.sf.net" xmlns:gcse="http://www.google.com" xmlns:date="http://exslt.org/dates-and-times"><code>&lt;?xml version="1.0" encoding="UTF-8"?&gt;
&lt;!DOCTYPE Configure PUBLIC "-//Jetty//Configure//EN" "http://www.eclipse.org/jetty/configure_9_3.dtd"&gt;

&lt;Configure class="org.eclipse.jetty.webapp.WebAppContext"&gt;
  &lt;Set name="contextPath"&gt;/wiki&lt;/Set&gt;
  &lt;Set name="war"&gt;&lt;SystemProperty name="myapp.home"/&gt;/myapp.war&lt;/Set&gt;
  &lt;Set name="extractWAR"&gt;false&lt;/Set&gt;
&lt;/Configure&gt;</code></pre><p>The next example retrieves the JavaEE Servlet context and sets an initialization parameter on it.
The <code class="literal">setAttribute</code> method can also be used to set a Servlet context attribute.
However, since the <code class="literal">web.xml</code> for the web application is processed after the deployment descriptor, the <code class="literal">web.xml</code> values overwrite identically named attributes from the deployment descriptor.</p><pre xmlns:jfetch="java:org.eclipse.jetty.xslt.tools.JavaSourceFetchExtension" xmlns:fetch="java:org.eclipse.jetty.xslt.tools.SourceFetchExtension" xmlns:d="http://docbook.org/ns/docbook" xmlns:l="http://docbook.sourceforge.net/xmlns/l10n/1.0" xmlns:xslthl="http://xslthl.sf.net" xmlns:gcse="http://www.google.com" xmlns:date="http://exslt.org/dates-and-times"><code>&lt;?xml version="1.0" encoding="UTF-8"?&gt;
&lt;!DOCTYPE Configure PUBLIC "-//Jetty//Configure//EN" "http://www.eclipse.org/jetty/configure_9_3.dtd"&gt;

&lt;Configure class="org.eclipse.jetty.webapp.WebAppContext"&gt;
  &lt;Set name="contextPath"&gt;/wiki&lt;/Set&gt;
  &lt;Set name="war"&gt;&lt;SystemProperty name="myapp.home"/&gt;/myapp.war&lt;/Set&gt;
  &lt;Get name="ServletContext"&gt;
     &lt;Call name="setInitParameter"&gt;
       &lt;Arg&gt;myapp.config&lt;/Arg&gt;
       &lt;Arg&gt;&lt;SystemProperty name="myapp.home"&gt;/config/app-config.xml&lt;/Arg&gt;
    &lt;/Call&gt;
  &lt;/Get&gt;
&lt;/Configure&gt;</code></pre><p>The following example sets a special <code class="literal">web.xml</code> override descriptor.
This descriptor is processed after the web application&#8217;s <code class="literal">web.xml</code>, so it may override identically named attributes.
This feature is useful when adding parameters or additional Servlet mappings without breaking open a packed WAR file.</p><pre xmlns:jfetch="java:org.eclipse.jetty.xslt.tools.JavaSourceFetchExtension" xmlns:fetch="java:org.eclipse.jetty.xslt.tools.SourceFetchExtension" xmlns:d="http://docbook.org/ns/docbook" xmlns:l="http://docbook.sourceforge.net/xmlns/l10n/1.0" xmlns:xslthl="http://xslthl.sf.net" xmlns:gcse="http://www.google.com" xmlns:date="http://exslt.org/dates-and-times"><code>&lt;?xml version="1.0" encoding="UTF-8"?&gt;
&lt;!DOCTYPE Configure PUBLIC "-//Jetty//Configure//EN" "http://www.eclipse.org/jetty/configure_9_3.dtd"&gt;

&lt;Configure class="org.eclipse.jetty.webapp.WebAppContext"&gt;
  &lt;Set name="contextPath"&gt;/wiki&lt;/Set&gt;
  &lt;Set name="war"&gt;&lt;SystemProperty name="myapp.home"/&gt;/myapp.war&lt;/Set&gt;
  &lt;Set name="overrideDescriptor"&gt;/opt/myapp/overlay-web.xml&lt;/Set&gt;
&lt;/Configure&gt;</code></pre><p>The next example configures not only the web application context, but also a database connection pool (see <a class="xref" href="jndi-datasource-examples.html" title="Datasource Examples">Datasource Examples</a>) that the application can then use.
If the <code class="literal">web.xml</code> does not include a reference to this data source, an override descriptor mechanism (as shown in the previous example) can be used to include it.</p><pre xmlns:jfetch="java:org.eclipse.jetty.xslt.tools.JavaSourceFetchExtension" xmlns:fetch="java:org.eclipse.jetty.xslt.tools.SourceFetchExtension" xmlns:d="http://docbook.org/ns/docbook" xmlns:l="http://docbook.sourceforge.net/xmlns/l10n/1.0" xmlns:xslthl="http://xslthl.sf.net" xmlns:gcse="http://www.google.com" xmlns:date="http://exslt.org/dates-and-times"><code>&lt;?xml version="1.0" encoding="UTF-8"?&gt;
&lt;!DOCTYPE Configure PUBLIC "-//Jetty//Configure//EN" "http://www.eclipse.org/jetty/configure_9_3.dtd"&gt;

&lt;Configure class="org.eclipse.jetty.webapp.WebAppContext"&gt;
  &lt;Set name="contextPath"&gt;/wiki&lt;/Set&gt;
  &lt;Set name="war"&gt;&lt;SystemProperty name="myapp.home"/&gt;/myapp.war&lt;/Set&gt;

  &lt;New id="DSTest" class="org.eclipse.jetty.plus.jndi.Resource"&gt;
    &lt;Arg&gt;&lt;/Arg&gt;
    &lt;Arg&gt;jdbc/DSTest&lt;/Arg&gt;
    &lt;Arg&gt;
      &lt;New class="org.apache.commons.dbcp.BasicDataSource"&gt;
        &lt;Set name="driverClassName"&gt;org.some.Driver&lt;/Set&gt;
        &lt;Set name="url"&gt;jdbc.url&lt;/Set&gt;
        &lt;Set name="username"&gt;jdbc.user&lt;/Set&gt;
        &lt;Set name="password"&gt;jdbc.pass&lt;/Set&gt;
      &lt;/New&gt;
    &lt;/Arg&gt;
  &lt;/New&gt;
&lt;/Configure&gt;</code></pre><p>There are many other settings that can be changed in a <a class="link" href="http://www.eclipse.org/jetty/javadoc/9.4.28-SNAPSHOT/org/eclipse/jetty/webapp/WebAppContext.html" target="_top"><code class="literal">WebAppContext</code></a>.
The <a class="link" href="http://www.eclipse.org/jetty/javadoc/9.4.28-SNAPSHOT/org/eclipse/jetty/webapp/WebAppContext.html" target="_top">javadoc</a> for <code class="literal">WebAppContext</code> is a good source of information.
Also see the documentation on <a class="link" href="troubleshooting.html#troubleshooting-zip-exceptions" title="Troubleshooting Zip Exceptions">avoiding zip file exceptions</a> for a description of <code class="literal">WebAppContext</code> settings that determine such things as whether or not the war is automatically unpacked during deployment, or whether certain sections of a webapp are copied to a temporary location.</p></div></div><script type="text/javascript">
      SyntaxHighlighter.all()
    </script><div class="navfooter"><hr><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="automatic-webapp-deployment.html"><i class="fa fa-chevron-left" aria-hidden="true"></i> Previous</a>&nbsp;</td><td width="20%" align="center"><a accesskey="u" href="configuring-deployment.html"><i class="fa fa-chevron-up" aria-hidden="true"></i> Top</a></td><td width="40%" align="right">&nbsp;<a accesskey="n" href="configuring-webapps.html">Next <i class="fa fa-chevron-right" aria-hidden="true"></i></a></td></tr><tr><td width="40%" align="left" valign="top">Automatic Web Application Deployment&nbsp;</td><td width="20%" align="center"><a accesskey="h" href="index.html"><i class="fa fa-home" aria-hidden="true"></i> Home</a></td><td width="40%" align="right" valign="top">&nbsp;Deployment Processing of WebAppContexts</td></tr></table></div><p xmlns:jfetch="java:org.eclipse.jetty.xslt.tools.JavaSourceFetchExtension" xmlns:fetch="java:org.eclipse.jetty.xslt.tools.SourceFetchExtension" xmlns:d="http://docbook.org/ns/docbook" xmlns:l="http://docbook.sourceforge.net/xmlns/l10n/1.0" xmlns:xslthl="http://xslthl.sf.net" xmlns:gcse="http://www.google.com" xmlns:date="http://exslt.org/dates-and-times"><div class="jetty-callout">
            See an error or something missing?
            <span class="callout"><a href="http://github.com/eclipse/jetty.project">Contribute to this documentation at
                <span class="website"><i class="fa fa-github" aria-hidden="true"></i> Github!</span></a></span><span style="float: right"><i>(Generated: 2020-03-10)</i></span></div></p></body></html>