![]() Version: 9.3.9.v20160517 |
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
Note
This feature is reintroduced in Jetty 9.0.4
The Jetty Overlay Deployer allows you to overlay multiple WAR files so that you can customise, configure, and deploy a web application without unpacking, modifying and repacking the WAR file. This has the following benefits:
This tutorial describes how to configure Jetty to use the Overlay deployer, and how to deploy multiple instances of a web application, using the JTrac application in the example.
Customising, configuring and deploying a web application bundled as a WAR file frequently includes some or all of these steps:
WEB-INF/web.xml file to set init parameters, add
filters/servlets or to configure JNDI resources.WEB-INF/.WEB-INF/ (for
example, jetty-web.xml or jboss-web.xml).The result is that the customisations and configurations blend into both the container and the WAR file. If you upgrade either the container or the base WAR file to a new version, it can be a very difficult and error prone task to identify all the changes that you have made, and to reapply them to a new version.
To solve the problems highlighted above, Jetty 7.4 introduces WAR overlays (a concept borrowed from the Maven WAR plugin). An overlay is basically just another WAR file, whose contents merge on top of the original WAR so that you can add or replace files. Jetty overlays also allow you to mix in fragments of web.xml, which means you can modify the configuration without replacing it.
The JTrac issue tracking web application is a good example of a typical web application, as it uses the usual suspects of libs: spring, hibernate, dom4j, commons-*, wicket, etc. The files for this demonstration are available in overlays-demo.tar.gz. You can expand it on top of the jetty distribution; this tutorial expands it to /tmp and installs the components step-by-step:
$ cd /tmp $ wget http://webtide.intalio.com/wp-content/uploads/2011/05/overlays-demo.tar.gz $ tar xfvz overlays-demo.tar.gz $ export OVERLAYS=/tmp/overlays$ cd /tmp $ wget http://webtide.intalio.com/wp-content/uploads/2011/05/overlays-demo.tar.gz $ tar xfvz overlays-demo.tar.gz $ export OVERLAYS=/tmp/overlays
Overlays support is included in jetty distributions from 7.4.1-SNAPSHOT onwards, so you can download a distribution from oss.sonatype.org or maven central and unpack into a directory. You need to edit the start.ini file so that it includes the overlay option and configuration file. The resulting file should look like:
OPTIONS=Server,jsp,jmx,resources,websocket,ext,overlay
etc/jetty.xml
etc/jetty-deploy.xml
etc/jetty-overlay.xmlThe smarts of this are in etc/jetty-deploy.xml, which installs the OverlayedAppProvider into the DeploymentManager. You can then start Jetty normally:
$ java -jar start.jar$ java -jar start.jar
Jetty is now listening on port 8080, but with no webapp deployed.
Important
You should conduct the rest of the tutorial in another window with the JETTY_HOME environment set to the jetty distribution directory.
You can download and deploy the WAR file for this demo using the following commands, which essentially downloads and extracts the WAR file to the $JETTY_HOME/overlays/webapps directory.
$ cd /tmp $ wget -O jtrac.zip http://sourceforge.net/projects/j-trac/files/jtrac/2.1.0/jtrac-2.1.0.zip/download $ jar xfv jtrac.zip jtrac/jtrac.war $ mv jtrac/jtrac.war $JETTY_HOME/overlays/webapps$ cd /tmp $ wget -O jtrac.zip http://sourceforge.net/projects/j-trac/files/jtrac/2.1.0/jtrac-2.1.0.zip/download $ jar xfv jtrac.zip jtrac/jtrac.war $ mv jtrac/jtrac.war $JETTY_HOME/overlays/webapps
When you have run these commands (or equivalent), you see in the Jetty server window a message saying that the OverlayedAppProvider has extracted and loaded the WAR file:
2011-05-06 10:31:54.678:INFO:OverlayedAppProvider:Extract jar:file:/tmp/jetty-distribution-7.4.1-SNAPSHOT/overlays/webapps/jtrac-2.1.0.war!/ to /tmp/jtrac-2.1.0_236811420856825222.extract
2011-05-06 10:31:55.235:INFO:OverlayedAppProvider:loaded jtrac-2.1.0@1304641914666Unlike the normal webapps dir, loading a WAR file from the overlays/webapp dir does not deploy the web application. It simply makes it available to use as the basis for templates and overlays.
A template overlay is a WAR structured directory/archive that contains just the files that you have added or modified to customize/configure the web application for all instances you plan to deploy.
You can install the demo template from the downloaded files with the command:
$ mv $OVERLAYS/jtracTemplate\=jtrac-2.1.0 $JETTY_HOME/overlays/templates/$ mv $OVERLAYS/jtracTemplate\=jtrac-2.1.0 $JETTY_HOME/overlays/templates/
In the Jetty server window, you should see the template loaded with a message like:
2011-05-06 11:00:08.716:INFO:OverlayedAppProvider:loaded jtracTemplate=jtrac-2.1.0@1304643608715The contents of the loaded template are as follows:
templates/jtracTemplate=jtrac-2.1.0
|__ WEB-INF
|__ classes
| |__ jtrac-init.properties
|__ log4j.properties
|__ overlay.xml
|__ template.xml
|__ web-overlay.xml<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE Configure PUBLIC "-//Jetty//Configure//EN" "http://www.eclipse.org/jetty/configure.dtd">
<Configure class="org.eclipse.jetty.webapp.WebAppContext">
<Set name="contextPath">/</Set>
</Configure><?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE Configure PUBLIC "-//Jetty//Configure//EN" "http://www.eclipse.org/jetty/configure.dtd">
<Configure class="org.eclipse.jetty.overlays.TemplateContext">
<Get name="resourceCache">
<Set name="useFileMappedBuffer">true</Set>
<Set name="maxCachedFileSize">10000000</Set>
<Set name="maxCachedFiles">1000</Set>
<Set name="maxCacheSize">64000000</Set>
</Get>
</Configure><?xml version="1.0" encoding="UTF-8"?>
<web-app xmlns="http://java.sun.com/xml/ns/j2ee"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xsi:schemaLocation="http://java.sun.com/xml/ns/j2ee http://java.sun.com/xml/ns/j2ee/web-app_2_4.xsd"
version="2.4">
<context-param>
<param-name>jtrac.home</param-name>
<param-value>/tmp/jtrac-${overlay.instance.classifier}</param-value>
</context-param>
<context-param>
<param-name>webAppRootKey</param-name>
<param-value>jtrac-${overlay.instance.classifier}</param-value>
</context-param>
<filter>
</web-app>Notice the parameterisation of values such as
${overlays.instance.classifier}, as this allows the configuration to
be in the template, and not customised for each instance.
Without the Overlay Deployer, you would still need to have configured all of the above, but rather than being in a single clear structure the configuration elements would have been either in the server’s common directory, the server’s webdefaults.xml (aka server.xml), or baked into the WAR file of each application instance using copied/modified files from the original. The Overlay Deployer allows you to make all these changes in one structure; moreover it allows you to parameterise some of the configuration, which facilitates easy multi-tenant deployment.
Now that you have installed a template, you can install one or more instance overlays to deploy the actual web applications:
$ mv /tmp/overlays/instances/jtracTemplate\=blue $JETTY_HOME/overlays/instances/ $ mv /tmp/overlays/instances/jtracTemplate\=red $JETTY_HOME/overlays/instances/ $ mv /tmp/overlays/instances/jtracTemplate\=blue $JETTY_HOME/overlays/instances/$ mv /tmp/overlays/instances/jtracTemplate\=blue $JETTY_HOME/overlays/instances/ $ mv /tmp/overlays/instances/jtracTemplate\=red $JETTY_HOME/overlays/instances/ $ mv /tmp/overlays/instances/jtracTemplate\=blue $JETTY_HOME/overlays/instances/
As each instance moves into place, you see the Jetty server window react and deploy that instance. Within each instance, there is the structure:
instances/jtracTemplate=red/
|__ WEB-INF
| |__ overlay.xml
|__ favicon.ico
|__ resources
|__ jtrac.css<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE Configure PUBLIC "-//Jetty//Configure//EN" "http://www.eclipse.org/jetty/configure.dtd">
<Configure class="org.eclipse.jetty.webapp.WebAppContext">
<Set name="virtualHosts">
<Array type="String">
<Item>127.0.0.2</Item>
<Item>red.myVirtualDomain.com</Item>
</Array>
</Set>
</Configure>You can now view the deployed instances by pointing your browser at http://127.0.0.1:8080, http://127.0.0.2:8080 and http://127.0.0.3:8080. The default username/password for JTrac is admin/admin.
Jetty hot deploys all overlays and tracks dependencies.