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. It offers 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:
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 and later have WAR overlays (a concept borrowed from the
Maven WAR plugin). An overlay is basically just another WAR file; its 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
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.xml
The 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
Jetty is now listening on port 8080, but with no webapp deployed.
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
download and extract 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
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@1304641914666
Unlike 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/
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@1304643608715 The 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="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">/</Set> </Configure>
<?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.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>
jtracTemplate=jtrac-2.1.0
to separate the name
of the template from the name of the WAR file in webapps that it applies to. If = is a problem, you can instead
use --.WEB-INF/classes/jtrac-init.properties
–Replaces the JTrac properties file with an
empty file, as the properties it contains are configured elsewhere.
web.xml
from the base WAR file; it can set init parameters and add/modify filters and servlets. In
this example it sets the application home and springs rootKey:<?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/
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="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="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.
Notice the following:
/tmp/jtrac-red
), set in templates web-overlay.xml
.overlay.xml
distinguishes the
instances.JTrac-2.2.0.war
becomes available,
you can just drop it into overlays/webapps
and then rename
jtracTemplate\=jtrac-2.1.0
to jtracTemplate\=jtrac-2.2.0
overlays-demo-jndi.tar.gz
, that uses
JNDI (needs options=jndi
, annotations and jetty-plus.xml
in
start.ini)
and shows how you can add extra JARs in the overlays.