Skip to main content
Jump to: navigation, search

Jetty/Tutorial/Configuring the Jetty Overlay Deployer

< Jetty‎ | Tutorial
Revision as of 11:52, 22 September 2011 by (Talk | contribs) (Undo revision 269610 by (Talk))


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:

  • You can keep the WAR file immutable, even signed, so that it is clear which version you have deployed.
  • All modifications you make to customise/configure the web application are separate WARs, and thus are easily identifiable for review and migration to new versions.
  • You can create a parameterised template overlay that contains common customisations and configuration that apply to many instances of the web application (for example, for multi-tenant deployment).
  • Because the layered deployment clearly identifies the common and instance specific components, Jetty is able to share classloaders and static resource caches for the template, greatly reducing the memory footprint of multiple instances.

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:

  • Editing the WEB-INF/web.xml file to set init parameters, add filters/servlets or to configure JNDI resources.
  • Editing other application specific configuration files in WEB-INF/*.
  • Editing container specific configuration files in WEB-INF/* (for example, jetty-web.xml or jboss-web.xml).
  • Adding/modifying static content such as images and CSS to create a style or themes for the web application.
  • Adding Jars to the container classpath for Datasource and other resources.
  • Modifying the container configuration to provide JNDI resources.

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.

JTrac Overlay Example

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
tar xfvz overlays-demo.tar.gz
export OVERLAYS=/tmp/overlays

Configuring Jetty for Overlays

Overlays support is included in jetty distributions from 7.4.1-SNAPSHOT onwards, so you can download a distribution from or [



Back to the top