| 1 |
[[!meta title="DEP-7: Java Web Application Packaging"]]
|
| 2 |
|
| 3 |
Title: Java Web Application Packaging
|
| 4 |
DEP: 7
|
| 5 |
State: DRAFT
|
| 6 |
Date: 2010-08-24
|
| 7 |
Drivers: Russ Allbery <rra@debian.org>
|
| 8 |
URL: http://dep.debian.net/deps/dep7
|
| 9 |
License: http://www.jclark.com/xml/copying.txt
|
| 10 |
Abstract:
|
| 11 |
Propose a file layout, set of conventions and best practices, and a
|
| 12 |
supporting script interface for packaging Java web applications
|
| 13 |
(servlets) and deploying them in containers.
|
| 14 |
|
| 15 |
# Introduction
|
| 16 |
|
| 17 |
Considerable progress has been made in recent years in packaging Java
|
| 18 |
libraries for Debian. However, less work has been done, to date, on
|
| 19 |
packaging Java servlets. These are common both in the free software world
|
| 20 |
as an implementation platform for web applications and in the enterprise
|
| 21 |
application development world.
|
| 22 |
|
| 23 |
Java servlets pose special challenges for Debian packaging, particularly
|
| 24 |
in the area of Filesystem Hierarchy Standard compliance. The normal
|
| 25 |
deployment method for a servlet is either as a monolithic WAR file or a
|
| 26 |
corresponding directory structure that contains everything of interest to
|
| 27 |
the servlet. This combines configuration files, code, and metadata in one
|
| 28 |
file or one directory tree, causing problems for proper configuration file
|
| 29 |
handling and integration of user customization.
|
| 30 |
|
| 31 |
Debian will also support multiple servlet containers, and a Java servlet
|
| 32 |
package should be able to deploy that servlet into the servlet container
|
| 33 |
of the user's choice. We should attempt to minimize the amount of work
|
| 34 |
required in each servlet package to support additional servlet containers
|
| 35 |
and centralize that work as much as possible in a helper utility and by
|
| 36 |
following standard deployment strategies that will be supported by Java
|
| 37 |
servlet containers.
|
| 38 |
|
| 39 |
The goal of this proposal is to provide the basis of a Java web
|
| 40 |
application (servlet) packaging policy, including file system layout and
|
| 41 |
best practices, and specify the interface of a deployment tool to
|
| 42 |
translate between a Debian-Policy-compliant file layout with proper
|
| 43 |
handling of configuration files and the deployment WAR file or directory
|
| 44 |
tree required by a web container. If accepted, it would be included in
|
| 45 |
the Java packaging policy for Debian.
|
| 46 |
|
| 47 |
This DEP will be discussed on the debian-java@lists.debian.org mailing
|
| 48 |
list.
|
| 49 |
|
| 50 |
# File Layout
|
| 51 |
|
| 52 |
A Java web application is normally deployed as either a WAR file or as an
|
| 53 |
exploded archive, which is the same file structure as a WAR file except
|
| 54 |
expressed on disk as a directory tree. All components of the servlet are
|
| 55 |
included in the WAR file, which in addition to JAR files, classes, and JSP
|
| 56 |
files includes the configuration file `WEB-INF/web.xml`. This file often
|
| 57 |
configures the application and controls such things as URL mappings, and
|
| 58 |
may need to be customized by the user. Some web applications have
|
| 59 |
additional configuration files that need customization, or may even use
|
| 60 |
JSP as a templating language and expect the installing user to edit some
|
| 61 |
JSP pages. However, the majority of the WAR file or exploded archive is
|
| 62 |
code.
|
| 63 |
|
| 64 |
Under Debian Policy and the Filesystem Hierarchy Standard,
|
| 65 |
architecture-independent code (the majority of a typical web application)
|
| 66 |
must be installed in `/usr/share`, but configuration files that the
|
| 67 |
installing user may want to edit to customize the application must be
|
| 68 |
installed in `/etc`. This means that different components of the web
|
| 69 |
application must be installed in different paths.
|
| 70 |
|
| 71 |
This proposal reserves two areas in the file system for Java web
|
| 72 |
applications:
|
| 73 |
|
| 74 |
* `/usr/share/java/webapps/<webapp-name>`: Contains all
|
| 75 |
architecture-independent files, such as JARs, class files, and JSPs,
|
| 76 |
that make up the web application and that are not expected to be edited
|
| 77 |
by the installing user.
|
| 78 |
|
| 79 |
* `/etc/java/webapps/<webapp-name>`: Contains all web application files
|
| 80 |
that should be treated as configuration files in the Debian definition
|
| 81 |
and possibly modified by the installing user to configure or customize
|
| 82 |
the application. This will normally include `WEB-INF/web.xml`.
|
| 83 |
|
| 84 |
Inside each of these directories, the layout of the files should match the
|
| 85 |
layout expected of a WAR file or exploded archive. So, in other words,
|
| 86 |
the `web.xml` file for a web application named `demo-viewer` should be
|
| 87 |
installed in `/etc/java/webapps/demo-viewer/WEB-INF/web.xml`.
|
| 88 |
|
| 89 |
If the same file exists in both `/usr/share/java/webapps` and
|
| 90 |
`/etc/java/webapps`, the file in the latter location will take precedence.
|
| 91 |
Users may therefore selectively replace files in a web application by
|
| 92 |
putting a file with the same name into the `/etc/java/webapps` directory
|
| 93 |
in the appropriate location.
|
| 94 |
|
| 95 |
`<webapp-name>` should normally match the name of the Debian package
|
| 96 |
providing that web application. It may contain a slash (`/`). If one
|
| 97 |
package provides multiple web applications, a naming convention of
|
| 98 |
`<package>/<webapp>` should be used. For example, if a package named
|
| 99 |
`apache-activemq` provided webapps `admin` and `fileserver`, the
|
| 100 |
`<webapp-name>`s for the above paths would be `apache-activemq/admin` and
|
| 101 |
`apache-activemq/fileserver`.
|
| 102 |
|
| 103 |
# Deployment
|
| 104 |
|
| 105 |
There are three common strategies for deploying a web application into a
|
| 106 |
web container:
|
| 107 |
|
| 108 |
1. Bundle the web application as a WAR file and drop that WAR file into
|
| 109 |
the web application root for the web container.
|
| 110 |
|
| 111 |
2. Install the web application files as an exploded archive under the web
|
| 112 |
application root for the web container.
|
| 113 |
|
| 114 |
3. Install the web application files elsewhere on the file system and then
|
| 115 |
point the web container at the web application files using a mechanism
|
| 116 |
such as a Tomcat context descriptor.
|
| 117 |
|
| 118 |
Approach 1 cannot be used directly by Debian packages since the WAR file
|
| 119 |
will contain both application code and configuration files with no way for
|
| 120 |
the user to change the configuration files. Approach 2 is unappealing for
|
| 121 |
Debian packages since the files would need to be installed in the web
|
| 122 |
application root for every possible web container to work out of the box
|
| 123 |
with any web container in Debian, but the user may wish to run multiple
|
| 124 |
web containers with different sets of applications.
|
| 125 |
|
| 126 |
Approach 3 is tempting, and is currently being used in Debian for some
|
| 127 |
Java web applications. However, in order to present the entire web
|
| 128 |
application as a unified tree, symlinks are required to allow
|
| 129 |
configuration files to be stored in `/etc` while the majority of the web
|
| 130 |
application is in `/usr/share`. Since upstream web application developers
|
| 131 |
normally don't anticipate needing to separate configuration files from
|
| 132 |
other web application files, this may require a complicated and fragile
|
| 133 |
nest of symlinks to move the appropriate files into `/etc`.
|
| 134 |
|
| 135 |
Finally, approach 1 is the most "typical" approach for deploying web
|
| 136 |
applications in Java enterprise environments, so many upstream developers
|
| 137 |
expect users to deploy web applications as WAR files and tailor their
|
| 138 |
documentation accordingly.
|
| 139 |
|
| 140 |
Therefore, the proposed way to deploy web applications on Debian is for
|
| 141 |
the web application package to generate a WAR file from its installed
|
| 142 |
files and any user-edited configuration files, taken from the
|
| 143 |
`/usr/share/java/webapps` and `/etc/java/webapps` paths defined above, and
|
| 144 |
deploy that WAR file into the appropriate web application roots for the
|
| 145 |
desired web containers. This will be done as follows:
|
| 146 |
|
| 147 |
1. From the `/usr/share/java/webapps` and `/etc/java/webapps` paths for
|
| 148 |
the web application being deployed, build a merged tree of files
|
| 149 |
created by first copying the `/usr/share/java/webapps` file tree and
|
| 150 |
then copying the `/etc/java/webapps` file tree over top of it. This
|
| 151 |
implements the semantics described above, where any file in
|
| 152 |
`/etc/java/webapps` overrides a file in `/usr/share/java/webapps` of
|
| 153 |
the same name.
|
| 154 |
|
| 155 |
1. Generate a WAR file from that merged directory tree.
|
| 156 |
|
| 157 |
1. Deploy that WAR file to a web container. If only one supported web
|
| 158 |
container for that web application is installed on the system, the WAR
|
| 159 |
file will be automatically deployed to that web container. If there
|
| 160 |
are multiple web containers on the system, the WAR file will be
|
| 161 |
deployed into the preferred one following a web container ranking
|
| 162 |
system (not yet specified).
|
| 163 |
|
| 164 |
1. On installation of the web application policy, it should be deployed
|
| 165 |
into the web container chosen by the default algorithm above with a
|
| 166 |
generic and safe configuration.
|
| 167 |
|
| 168 |
1. On upgrade or reconfiguration of the web application, redeploy the WAR
|
| 169 |
file into whichever web container it was deployed.
|
| 170 |
|
| 171 |
1. On removal of the web application package, undeploy the WAR file from
|
| 172 |
any web containers to which it was deployed.
|
| 173 |
|
| 174 |
These steps will be done with a tool that can also be run directly by the
|
| 175 |
user, allowing the user to build a WAR file without deploying it, undeploy
|
| 176 |
a web application from a particular web container, deploy a web
|
| 177 |
application into the non-default web container, and similar actions.
|
| 178 |
|
| 179 |
Whenever the user changes any of the configuration files for a web
|
| 180 |
application, they will have to redeploy the application using this same
|
| 181 |
tool. This should be documented in README.Debian for any web application
|
| 182 |
using this system, and also in a README file in `/etc/java/webapps`.
|
| 183 |
|
| 184 |
Also see the
|
| 185 |
[draft interface for the deployment tool](java-deploy-webapp.pod).
|
| 186 |
|
| 187 |
# TODO
|
| 188 |
|
| 189 |
The following issues still need to be addressed:
|
| 190 |
|
| 191 |
* How to use the Endorsed Standards Override Mechanism to replace the XML
|
| 192 |
parser for a particular web application or do the other overrides that
|
| 193 |
require using this mechanism.
|
| 194 |
|
| 195 |
* Web application logging policy.
|
| 196 |
|
| 197 |
* Web application SecurityManager policy files.
|
| 198 |
|
| 199 |
* Determine a ranking system for web application containers to determine
|
| 200 |
which web container a web application is deployed into when multiple
|
| 201 |
containers are installed on the system.
|
| 202 |
|
| 203 |
* Does the deployment tool need to also deploy (and remove) extra
|
| 204 |
configuration files that are specific to web containers, such as files
|
| 205 |
for `/etc/tomcat6/policy.d`?
|
| 206 |
|
| 207 |
# License
|
| 208 |
|
| 209 |
Copyright 2010 Board of Trustees, Leland Stanford Jr. University
|
| 210 |
|
| 211 |
Permission is hereby granted, free of charge, to any person obtaining a
|
| 212 |
copy of this software and associated documentation files (the “Software”),
|
| 213 |
to deal in the Software without restriction, including without limitation
|
| 214 |
the rights to use, copy, modify, merge, publish, distribute, sublicense,
|
| 215 |
and/or sell copies of the Software, and to permit persons to whom the
|
| 216 |
Software is furnished to do so, subject to the following conditions:
|
| 217 |
|
| 218 |
The above copyright notice and this permission notice shall be included in
|
| 219 |
all copies or substantial portions of the Software.
|
| 220 |
|
| 221 |
THE SOFTWARE IS PROVIDED “AS IS”, WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
|
| 222 |
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
|
| 223 |
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL
|
| 224 |
THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
|
| 225 |
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING
|
| 226 |
FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER
|
| 227 |
DEALINGS IN THE SOFTWARE.
|
| 228 |
|
| 229 |
# Changes
|
| 230 |
|
| 231 |
* 2010-08-24: Initial version based on a preliminary proposal to the
|
| 232 |
debian-java mailing list.
|
Parent Directory
| 
Revision Log