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