Difference between revisions of "Jetty/Tutorial/Configuring the Jetty Overlay Deployer"

m(New page: =Jetty Overlayed WebApp Deployer= The Jetty Overlay Deployer allows you to overlay multiple WAR files so that you can customize, configure, and deploy a web application without the need t...)

The Jetty Overlay Deployer allows you to overlay multiple WAR files so that you can customize, configure, and deploy a web application without the need to unpack, modify and repack the WAR file. This has the following benefits:

+

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.

* You can keep the WAR file immutable, even signed, so that it is clear which version you have deployed.

Line 8:

Line 8:

* 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.

* 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 document describes how to configure Jetty to use the Overlay deployer, and how to deploy multiple instances of a web application, in this example, JTrac.

+

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.

* Adding/modifying static content such as images and css to style/theme the web application.

+

* 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.

* Adding Jars to the container classpath for Datasource and other resources.

* Modifying the container configuration to provide JNDI resources.

* Modifying the container configuration to provide JNDI resources.

Line 25:

Line 25:

==Overlays==

==Overlays==

−

To solve the problems highlighted above, Jetty 7.4 introduces WAR overlays (a concept borrowed from the [http://maven.apache.org/plugins/maven-war-plugin/overlays.html Maven WAR plugin]). An overlay is basically just another WAR file, whose contents are merged on top of the original WAR so that you can add or replace files.

+

To solve the problems highlighted above, Jetty 7.4 introduces WAR overlays (a concept borrowed from the [http://maven.apache.org/plugins/maven-war-plugin/overlays.html 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 <tt>web.xml</tt>, which means you can modify the configuration without replacing it.

−

Jetty overlays also allow mixin fragments of <tt>web.xml</tt>, so the you can modify the configuration without replacing it.

+

−

==Jtrac Overlay Example==

+

==JTrac Overlay Example==

−

The [http://www.jtrac.info/ 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 [http://www.jtrac.info/ 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 [http://webtide.intalio.com/wp-content/uploads/2011/05/overlays-demo.tar.gz overlays-demo.tar.gz]. You can expand it on top of the jetty distribution; this tutorial expands it to <code>/tmp</code> and installs the components step-by-step:

−

The files for this demonstration are available in [http://webtide.intalio.com/wp-content/uploads/2011/05/overlays-demo.tar.gz overlays-demo.tar.gz]. You can expand it on top of the jetty distribution, but tutorial expands it to <code>/tmp</code> and installs the components step-by-step:

+

<div class="wp_syntax"><div class="code">

<div class="wp_syntax"><div class="code">

Line 44:

Line 42:

==Configuring Jetty for 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 [https://oss.sonatype.org/content/groups/jetty-with-staging/org/eclipse/jetty/jetty-distribution/ oss.sonatype.org] or [http://search.maven.org/#browse|-162561384 maven central](once 7.4.1 is released) and unpack into a directory. The start.ini file then needs to be edited so that it includes the overlay option and configuration file. The resulting file should look like:

+

Overlays support is included in jetty distributions from 7.4.1-SNAPSHOT onwards, so you can download a distribution from [https://oss.sonatype.org/content/groups/jetty-with-staging/org/eclipse/jetty/jetty-distribution/ oss.sonatype.org] or [http://search.maven.org/#browse|-162561384 maven central] and unpack into a directory. You need to edit the <tt>start.ini</tt> file so that it includes the overlay option and configuration file. The resulting file should look like:

<div class="wp_syntax"><div class="code">

<div class="wp_syntax"><div class="code">

Line 55:

Line 53:

</div></div>

</div></div>

−

The smarts of this are in <tt>etc/jetty-deploy.xml</tt> files, which installs the OverlayedAppProvider into the DeploymentManager. You can then start Jetty normally:

+

The smarts of this are in <tt>etc/jetty-deploy.xml</tt>, which installs the OverlayedAppProvider into the DeploymentManager. You can then start Jetty normally:

<div class="wp_syntax"><div class="code">

<div class="wp_syntax"><div class="code">

Line 63:

Line 61:

</div></div>

</div></div>

−

Jetty is now listening on port 8080, but with no webapp deployed. The rest of the tutorial should be conducted in another window with the <code>JETTY_HOME</code> environment set to the jetty distribution directory.

+

Jetty is now listening on port 8080, but with no webapp deployed.

+

+

{{Note|Important: You should conduct the rest of the tutorial in another window with the <code>JETTY_HOME</code> environment set to the jetty distribution directory.}}

==Installing the WebApp==

==Installing the WebApp==

Line 87:

Line 87:

</div></div>

</div></div>

−

Unlike the normal <code>webapps</code> dir, loading a war file from the <code>overlays/webapp</code> dir does not deploy the webapplication. It simply makes it available to be used as the basis for templates and overlays.

+

Unlike the normal <code>webapps</code> dir, loading a WAR file from the <code>overlays/webapp</code> dir does not deploy the web application. It simply makes it available to use as the basis for templates and overlays.

==Installing a Template Overlay==

==Installing a Template Overlay==

−

A template overlay is a WAR structured directory/archive that contains just the files that have been added or modified to customize/configure the webapplication for all instances that will be deployed.

+

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.

−

The demo template can be installed from the downloaded files with the command:

+

You can install the demo template from the downloaded files with the command:

<div class="wp_syntax"><div class="code">

<div class="wp_syntax"><div class="code">

Line 109:

Line 109:

</div></div>

</div></div>

−

The contents of the loaded template is as follows:

+

The contents of the loaded template are as follows:

<div class="wp_syntax"><div class="code">

<div class="wp_syntax"><div class="code">

Line 124:

Line 124:

</div></div>

</div></div>

−

The name of the template directory (or it could be a war) uses the ‘=’ character in <code>jtracTemplate=jtrac-2.1.0</code> to separates the name of the template from the name of the WAR file in webapps that it applies to. If <code><nowiki>=</nowiki></code> is a problem, then <code>--</code> may also be used.

+

*The name of the template directory (or it could be a WAR) uses the ‘=’ character in <code>jtracTemplate=jtrac-2.1.0</code> to separate the name of the template from the name of the WAR file in webapps that it applies to. If <code><nowiki>=</nowiki></code> is a problem, then you can instead use <code>--</code>.

−

<code>WEB-INF/classes/jtrac-init.properties</code> – replaces the jtrac properties file with an empty file, as the properties contained within it are configured elsewhere

+

*<code>WEB-INF/classes/jtrac-init.properties</code>–Replaces the JTrac properties file with an empty file, as the properties it contains are configured elsewhere.

−

<code>WEB-INF/log4j.properties</code> – configures the logging for all instances of the template.

+

*<code>WEB-INF/log4j.properties</code>–Configures the logging for all instances of the template.

−

<code>WEB-INF/overlay.xml</code> – a Jetty XML formatted IoC file that is used to inject/configure the ContextHandler for each instances. In this case it just sets up the context path:

+

*<code>WEB-INF/overlay.xml</code>–A Jetty XML formatted IoC file that injects/configures the ContextHandler for each instance. In this case it just sets up the context path:

<div class="wp_syntax"><div class="code">

<div class="wp_syntax"><div class="code">

Line 142:

Line 142:

</div></div>

</div></div>

−

<code>WEB-INF/template.xml</code> – a Jetty XML formatted IoC file that is used to inject/configure the resource cache and classloader that is shared by all instances of the template. It is run only once per load of the template:

+

*<code>WEB-INF/template.xml</code> – a Jetty XML formatted IoC file that injects/configures the resource cache and classloader that all instances of the template share. It runs only once per load of the template:

<div class="wp_syntax"><div class="code">

<div class="wp_syntax"><div class="code">

Line 159:

Line 159:

</div></div>

</div></div>

−

<code>WEB-INF/web-overlay.xml</code> – a web.xml fragment that is overlayed on top of the web.xml from the base WAR file, that can set init parameters and add/modify filters and servlets. In this it sets the application home and springs rootKey:

+

*<code>WEB-INF/web-overlay.xml</code>–a web.xml fragment that Jetty overlays on top of the <code>web.xml</code> 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:

<div class="wp_syntax"><div class="code">

<div class="wp_syntax"><div class="code">

Line 181:

Line 181:

</div></div>

</div></div>

−

Note the use of parameterisation of values such as <code>${overlays.instance.classifier}</code>, as this allows the configuration to be made in the template and not customised for each instance.

+

Notice the parameterisation of values such as <code>${overlays.instance.classifier}</code>, as this allows the configuration to be in the template, and not customised for each instance.

−

Without the overlayed deployer, all the configurations above would still need to have been made, but rather that being in a single clear structure they would have been either in the servers common directory, the servers webdefaults.xml (aka server.xml), or baked into the WAR file of each application instance using copied/modified files from the original. The overlayed deployer allows us to make all these changes in one structure, more over it allows some of the configuration to be parameterised to facilitate easy multi-tenant deployment.

+

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 <code>webdefaults.xml</code> (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.

==Installing an Instance Overlay==

==Installing an Instance Overlay==

−

Now that we have installed a template, we can install one or more instance overlays, which deploy the actual web applications:

+

Now that you have installed a template, you can install one or more instance overlays to deploy the actual web applications:

<div class="wp_syntax"><div class="code">

<div class="wp_syntax"><div class="code">

Line 197:

Line 197:

</div></div>

</div></div>

−

As each instance is moved into place, you will see the jetty server window react and deploy that instance. Within each instance, there is the structure:

+

As each instance moves into place, you see the Jetty server window react and deploy that instance. Within each instance, there is the structure:

<div class="wp_syntax"><div class="code">

<div class="wp_syntax"><div class="code">

Line 210:

Line 210:

</div></div>

</div></div>

−

<code>WEB-INF/overlay.xml</code> – a Jetty XML format IoC file that injects/configures the context for the instance. In this case it sets up a virtual host for the instance:

+

*<code>WEB-INF/overlay.xml</code>–a Jetty XML format IoC file that injects/configures the context for the instance. In this case it sets up a virtual host for the instance:

<div class="wp_syntax"><div class="code">

<div class="wp_syntax"><div class="code">

Line 227:

Line 227:

</div></div>

</div></div>

−

<code>favicon.ico</code> – replaces the icon in the base war with one themed for the instance colour.

+

*<code>favicon.ico</code>–Replaces the icon in the base WAR with one that has a theme for the instance, in this case red, blue, or green.

−

<code>resources/jtrac.css</code> – replaces the style sheet from the base war with one themed for the instance colour

+

*<code>resources/jtrac.css</code>–Replaces the style sheet from the base WAR with one that his a theme for the instance.

−

The deployed instances can now be viewed 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.

+

You can now view the deployed instances by pointing your browser at <nowiki>http://127.0.0.1:8080</nowiki>, <nowiki>http://127.0.0.2:8080</nowiki> and <nowiki>http://127.0.0.3:8080</nowiki>. The default username/password for JTrac is admin/admin.

−

==Things to know and notice==

+

==Things to Know and Notice==

−

* Each instance is themed with images and styles sheets from the instance overlay.

+

* Each instance has themes with images and style sheets from the instance overlay.

−

* Each instance is running with it’s own application directory (eg. <code>/tmp/jtrac-red</code>), that is set templates web-overlay.xml.

+

* Each instance is running with its own application directory (that is, <code>/tmp/jtrac-red</code>), set in templates web-overlay.xml.

−

* The instances are distinguished by virtual host that is set in the instance overlay.xml

+

* A virtual host set in the instance <code>overlay.xml</code> distinguishes the instances.

−

* The static content from the base war and template are shared between all instances. Specifically there is a shared ResourceCache so only a single instance of each static content is loaded into memory.

+

* All instances share static content from the base WAR and template. Specifically there is a shared ResourceCache so only a single instance of each static content is loaded into memory.

−

* The classloader at the base war and template level is shared between all instances, so that only a single instance of common classes is loaded into memory. Classes with non shared statics can be configured to load in the instances classloader.

+

* All instances share the classloader at the base WAR and template level, so that only a single instance of common classes is loaded into memory. You can configure classes with non shared statics to load in the instances classloader.

−

* All overlays are hot deployed and dependencies tracked. If an XML is touched in an instance, it is redeployed. If an XML is touched in a template, then all instances using it are redeployed. If a WAR file is touched, then all templates and all instances dependant on it are redeployed.

+

* Jetty hot deploys all overlays and tracks dependencies.

−

* New versions can easily be deployed. Eg when jtrac-2.2.0.war becomes available, it can just be dropped into overlays/webapps and then rename jtracTemplate\=jtrac-2.1.0 to jtracTemplate\=jtrac-2.2.0

+

**If an XML changes in an instance, Jetty redeploys it.

−

* There is a fuller version of this demo in [http://webtide.intalio.com/wp-content/uploads/2011/05/overlays-demo-jndi.tar.gz overlays-demo-jndi.tar.gz], that uses JNDI (needs options=jndi,annotations and jetty-plus.xml in start.ini) and shows how extra jars can be added in the overlays.

+

**If an XML changes in a template, then Jetty redeploys all instances using it.

+

**If a WAR file changes, then Jetty redeploys all templates and all instances dependant on it.

+

* You can esaily deploy new versions. For example, when 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

+

* There is a fuller version of this demo in [http://webtide.intalio.com/wp-content/uploads/2011/05/overlays-demo-jndi.tar.gz overlays-demo-jndi.tar.gz], that uses JNDI (needs options=jndi, annotations and <code>jetty-plus.xml</code> in <code>start.ini</code>) and shows how you can add extra JARs in the overlays.

Jetty Overlay WebApp Deployer

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.

Overview

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.

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.

Overlays

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:

Configuring Jetty for 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:

The name of the template directory (or it could be a WAR) uses the ‘=’ character in 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, then 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-INF/log4j.properties–Configures the logging for all instances of the template.

WEB-INF/overlay.xml–A Jetty XML formatted IoC file that injects/configures the ContextHandler for each instance. In this case it just sets up the context path:

WEB-INF/web-overlay.xml–a web.xml fragment that Jetty overlays on top of the 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:

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.

Installing an Instance Overlay

Now that you have installed a template, you can install one or more instance overlays to deploy the actual web applications:

favicon.ico–Replaces the icon in the base WAR with one that has a theme for the instance, in this case red, blue, or green.

resources/jtrac.css–Replaces the style sheet from the base WAR with one that his a theme for the instance.

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.

Things to Know and Notice

Each instance has themes with images and style sheets from the instance overlay.

Each instance is running with its own application directory (that is, /tmp/jtrac-red), set in templates web-overlay.xml.

A virtual host set in the instance overlay.xml distinguishes the instances.

All instances share static content from the base WAR and template. Specifically there is a shared ResourceCache so only a single instance of each static content is loaded into memory.

All instances share the classloader at the base WAR and template level, so that only a single instance of common classes is loaded into memory. You can configure classes with non shared statics to load in the instances classloader.

Jetty hot deploys all overlays and tracks dependencies.

If an XML changes in an instance, Jetty redeploys it.

If an XML changes in a template, then Jetty redeploys all instances using it.

If a WAR file changes, then Jetty redeploys all templates and all instances dependant on it.

You can esaily deploy new versions. For example, when 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

There is a fuller version of this demo in 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.