container/webapps/docs/appdev/deployment.xml - tomcat55 - Git at Google

 <?xml version="1.0"?>
 <!DOCTYPE document [
   <!ENTITY project SYSTEM "project.xml">
 ]>
 <document url="deployment.html">

   &project;

   <properties>
     <author email="craigmcc@apache.org">Craig R. McClanahan</author>
     <title>Deployment</title>
   </properties>

 <body>


 <section name="Background">

 <p>Before describing how to organize your source code directories,
 it is useful to examine the runtime organization of a web application.
 Prior to the Servlet API Specification, version 2.2, there was little
 consistency between server platforms.  However, servers that conform
 to the 2.2 (or later) specification are required to accept a
 <em>Web Application Archive</em> in a standard format, which is discussed
 further below.</p>

 <p>A web application is defined as a hierarchy of directories and files
 in a standard layout.  Such a hierarchy can be accessed in its "unpacked"
 form, where each directory and file exists in the filesystem separately,
 or in a "packed" form known as a Web ARchive, or WAR file.  The former format
 is more useful during development, while the latter is used when you
 distribute your application to be installed.</p>

 <p>The top-level directory of your web application hierarchy is also the
 <em>document root</em> of your application.  Here, you will place the HTML
 files and JSP pages that comprise your application's user interface.  When the
 system administrator deploys your application into a particular server, he
 or she assigns a <em>context path</em> to your application (a later section
 of this manual describes deployment on Tomcat).  Thus, if the
 system administrator assigns your application to the context path
 <code>/catalog</code>, then a request URI referring to
 <code>/catalog/index.html</code> will retrieve the <code>index.html</code>
 file from your document root.</p>

 </section>


 <section name="Standard Directory Layout">

 <p>To facilitate creation of a Web Application Archive file in the required
 format, it is convenient to arrange the "executable" files of your web
 application (that is, the files that Tomcat actually uses when executing
 your app) in the same organization as required by the WAR format itself.
 To do this, you will end up with the following contents in your
 application's "document root" directory:</p>
 <ul>
 <li><strong>*.html, *.jsp, etc.</strong> - The HTML and JSP pages, along
     with other files that must be visible to the client browser (such as
     JavaScript, stylesheet files, and images) for your application.
     In larger applications you may choose to divide these files into
     a subdirectory hierarchy, but for smaller apps, it is generally
     much simpler to maintain only a single directory for these files.
     <br/><br/></li>
 <li><strong>/WEB-INF/web.xml</strong> - The <em>Web Application Deployment
     Descriptor</em> for your application.  This is an XML file describing
     the servlets and other components that make up your application,
     along with any initialization parameters and container-managed
     security constraints that you want the server to enforce for you.
     This file is discussed in more detail in the following subsection.
     <br/><br/></li>
 <li><strong>/WEB-INF/classes/</strong> - This directory contains any Java
     class files (and associated resources) required for your application,
     including both servlet and non-servlet classes, that are not combined
     into JAR files.  If your classes are organized into Java packages,
     you must reflect this in the directory hierarchy under
     <code>/WEB-INF/classes/</code>.  For example, a Java class named
     <code>com.mycompany.mypackage.MyServlet</code>
     would need to be stored in a file named
     <code>/WEB-INF/classes/com/mycompany/mypackage/MyServlet.class</code>.
     <br/><br/></li>
 <li><strong>/WEB-INF/lib/</strong> - This directory contains JAR files that
     contain Java class files (and associated resources) required for your
     application, such as third party class libraries or JDBC drivers.</li>
 </ul>

 <p>When you install an application into Tomcat (or any other
 2.2/2.3-compatible server), the classes in the <code>WEB-INF/classes/</code>
 directory, as well as all classes in JAR files found in the
 <code>WEB-INF/lib/</code> directory, are made visible to other classes
 within your particular web application.  Thus, if
 you include all of the required library classes in one of these places (be
 sure to check licenses for redistribution rights for any third party libraries
 you utilize), you will simplify the installation of your web application --
 no adjustment to the system class path (or installation of global library
 files in your server) will be necessary.</p>

 <p>Much of this information was extracted from Chapter 9 of the Servlet
 API Specification, version 2.3, which you should consult for more details.</p>

 </section>


 <section name="Shared Library Files">

 <p>Like most servlet containers, Tomcat 5 also supports mechanisms to install
 library JAR files (or unpacked classes) once, and make them visible to all
 installed web applications (without having to be included inside the web
 application itself.  The details of how Tomcat locates and shares such
 classes are described in the
 <a href="../class-loader-howto.html">Class Loader HOW-TO</a> documentation.
 For the purposes of our discussion, there are two locations that are commonly
 used within a Tomcat 5 installation for shared code:</p>
 <ul>
 <li><strong>$CATALINA_HOME/common/lib</strong> - JAR files placed here are
     visible both to web applications and internal Tomcat code.  This is a
     good place to put JDBC drivers that are required for both your application
     and internal Tomcat use (such as for a JDBCRealm).
     <br/><br/></li>
 <li><strong>$CATALINA_HOME/shared/lib</strong> - JAR files placed here are
     visible to all web applications, but not to internal Tomcat code.  This
     is the right place for shared libraries that are specific to your
     application.<br/><br/></li>
 </ul>

 <p>Out of the box, a standard Tomcat 5 installation includes a variety
 of pre-installed shared library files, including:</p>
 <ul>
 <li>The <em>Servlet 2.4</em> and <em>JSP 2.0</em> APIs that are fundamental
     to writing servlets and JavaServer Pages.<br/><br/></li>
 <li>An <em>XML Parser</em> compliant with the JAXP (version 1.2) APIs, so
     your application can perform DOM-based or SAX-based processing of
     XML documents.<br/><br/></li>
 </ul>

 </section>


 <section name="Web Application Deployment Descriptor">

     <blockquote><em>
     <p>The description below uses the variable name $CATALINA_HOME
     to refer to the directory into which you have installed Tomcat 5,
     and is the base directory against which most relative paths are
     resolved.  However, if you have configured Tomcat 5 for multiple
     instances by setting a CATALINA_BASE directory, you should use
     $CATALINA_BASE instead of $CATALINA_HOME for each of these
     references.</p>
     </em></blockquote>

 <p>As mentioned above, the <code>/WEB-INF/web.xml</code> file contains the
 Web Application Deployment Descriptor for your application.  As the filename
 extension implies, this file is an XML document, and defines everything about
 your application that a server needs to know (except the <em>context path</em>,
 which is assigned by the system administrator when the application is
 deployed).</p>

 <p>The complete syntax and semantics for the deployment descriptor is defined
 in Chapter 13 of the Servlet API Specification, version 2.3.  Over time, it
 is expected that development tools will be provided that create and edit the
 deployment descriptor for you.  In the meantime, to provide a starting point,
 a <a href="web.xml.txt" target="_new">basic web.xml file</a>
 is provided.  This file includes comments that describe the purpose of each
 included element.</p>

 <p><strong>NOTE</strong> - The Servlet Specification includes a Document
 Type Descriptor (DTD) for the web application deployment descriptor, and
 Tomcat 5 enforces the rules defined here when processing your application's
 <code>/WEB-INF/web.xml</code> file.  In particular, you <strong>must</strong>
 enter your descriptor elements (such as <code>&lt;filter&gt;</code>,
 <code>&lt;servlet&gt;</code>, and <code>&lt;servlet-mapping&gt;</code> in
 the order defined by the DTD (see Section 13.3).</p>

 </section>


 <section name="Tomcat Context Descriptor">

     <blockquote><em>
     <p>The description below uses the variable name $CATALINA_HOME
     to refer to the directory into which you have installed Tomcat 5,
     and is the base directory against which most relative paths are
     resolved.  However, if you have configured Tomcat 5 for multiple
     instances by setting a CATALINA_BASE directory, you should use
     $CATALINA_BASE instead of $CATALINA_HOME for each of these
     references.</p>
     </em></blockquote>

 <p>A /META-INF/context.xml file can be used to define Tomcat specific
 configuration options, such as loggers, data sources, session manager
 configuration and more. This XML file must contain one Context element, which
 will be considered as if it was the child of the Host element corresponding
 to the Host to which the  The Tomcat configuration documentation contains
 information on the Context element.</p>

 </section>


 <section name="Deployment With Tomcat 5">

 <p>In order to be executed, a web application must be deployed on
 a servlet container.  This is true even during development.
 We will describe using Tomcat 5 to provide the execution environment.
 A web application can be deployed in Tomcat by one of the following
 approaches:</p>
 <ul>
 <li><em>Copy unpacked directory hierarchy into a subdirectory in directory
     <code>$CATALINA_HOME/webapps/</code></em>.  Tomcat will assign a
     context path to your application based on the subdirectory name you
     choose.  We will use this technique in the <code>build.xml</code>
     file that we construct, because it is the quickest and easiest approach
     during development.  Be sure to restart Tomcat after installing or
     updating your application.
     <br/><br/></li>
 <li><em>Copy the web application archive file into directory
     <code>$CATALINA_HOME/webapps/</code></em>.  When Tomcat is started, it will
     automatically expand the web application archive file into its unpacked
     form, and execute the application that way.  This approach would typically
     be used to install an additional application, provided by a third party
     vendor or by your internal development staff, into an existing
     Tomcat installation.  <strong>NOTE</strong> - If you use this approach,
     and wish to update your application later, you must both replace the
     web application archive file <strong>AND</strong> delete the expanded
     directory that Tomcat created, and then restart Tomcat, in order to reflect
     your changes.
     <br/><br/></li>
 <li><em>Use the Tomcat 5 "Manager" web application to deploy and undeploy
     web applications</em>.  Tomcat 5 includes a web application, deployed
     by default on context path <code>/manager</code>, that allows you to
     deploy and undeploy applications on a running Tomcat server without
     restarting it.  See the administrator documentation (TODO: hyperlink)
     for more information on using the Manager web application.<br/><br/></li>
 <li><em>Use "Manager" Ant Tasks In Your Build Script</em>.  Tomcat 5
     includes a set of custom task definitions for the <code>Ant</code>
     build tool that allow you to automate the execution of commands to the
     "Manager" web application.  These tasks are used in the Tomcat deployer.
     <br/><br/></li>
 <li><em>Use the Tomcat Deployer</em>.  Tomcat 5 includes a packaged tool
     bundling the Ant tasks, and can be used to automatically precompile JSPs
     which are part of the web application before deployment to the server.
     <br/><br/></li>
 </ul>

 <p>Deploying your app on other servlet containers will be specific to each
 container, but all containers compatible with the Servlet API Specification
 (version 2.2 or later) are required to accept a web application archive file.
 Note that other containers are <strong>NOT</strong> required to accept an
 unpacked directory structure (as Tomcat does), or to provide mechanisms for
 shared library files, but these features are commonly available.</p>

 </section>


 </body>
 </document>
	<?xml version="1.0"?>
	<!DOCTYPE document [
	<!ENTITY project SYSTEM "project.xml">
	]>
	<document url="deployment.html">

	&project;

	<properties>
	<author email="craigmcc@apache.org">Craig R. McClanahan</author>
	<title>Deployment</title>
	</properties>

	<body>


	<section name="Background">

	<p>Before describing how to organize your source code directories,
	it is useful to examine the runtime organization of a web application.
	Prior to the Servlet API Specification, version 2.2, there was little
	consistency between server platforms. However, servers that conform
	to the 2.2 (or later) specification are required to accept a
	<em>Web Application Archive</em> in a standard format, which is discussed
	further below.</p>

	<p>A web application is defined as a hierarchy of directories and files
	in a standard layout. Such a hierarchy can be accessed in its "unpacked"
	form, where each directory and file exists in the filesystem separately,
	or in a "packed" form known as a Web ARchive, or WAR file. The former format
	is more useful during development, while the latter is used when you
	distribute your application to be installed.</p>

	<p>The top-level directory of your web application hierarchy is also the
	<em>document root</em> of your application. Here, you will place the HTML
	files and JSP pages that comprise your application's user interface. When the
	system administrator deploys your application into a particular server, he
	or she assigns a <em>context path</em> to your application (a later section
	of this manual describes deployment on Tomcat). Thus, if the
	system administrator assigns your application to the context path
	<code>/catalog</code>, then a request URI referring to
	<code>/catalog/index.html</code> will retrieve the <code>index.html</code>
	file from your document root.</p>

	</section>


	<section name="Standard Directory Layout">

	<p>To facilitate creation of a Web Application Archive file in the required
	format, it is convenient to arrange the "executable" files of your web
	application (that is, the files that Tomcat actually uses when executing
	your app) in the same organization as required by the WAR format itself.
	To do this, you will end up with the following contents in your
	application's "document root" directory:</p>
	<ul>
	<li><strong>.html, .jsp, etc.</strong> - The HTML and JSP pages, along
	with other files that must be visible to the client browser (such as
	JavaScript, stylesheet files, and images) for your application.
	In larger applications you may choose to divide these files into
	a subdirectory hierarchy, but for smaller apps, it is generally
	much simpler to maintain only a single directory for these files.
	<br/><br/></li>
	<li><strong>/WEB-INF/web.xml</strong> - The <em>Web Application Deployment
	Descriptor</em> for your application. This is an XML file describing
	the servlets and other components that make up your application,
	along with any initialization parameters and container-managed
	security constraints that you want the server to enforce for you.
	This file is discussed in more detail in the following subsection.
	<br/><br/></li>
	<li><strong>/WEB-INF/classes/</strong> - This directory contains any Java
	class files (and associated resources) required for your application,
	including both servlet and non-servlet classes, that are not combined
	into JAR files. If your classes are organized into Java packages,
	you must reflect this in the directory hierarchy under
	<code>/WEB-INF/classes/</code>. For example, a Java class named
	<code>com.mycompany.mypackage.MyServlet</code>
	would need to be stored in a file named
	<code>/WEB-INF/classes/com/mycompany/mypackage/MyServlet.class</code>.
	<br/><br/></li>
	<li><strong>/WEB-INF/lib/</strong> - This directory contains JAR files that
	contain Java class files (and associated resources) required for your
	application, such as third party class libraries or JDBC drivers.</li>
	</ul>

	<p>When you install an application into Tomcat (or any other
	2.2/2.3-compatible server), the classes in the <code>WEB-INF/classes/</code>
	directory, as well as all classes in JAR files found in the
	<code>WEB-INF/lib/</code> directory, are made visible to other classes
	within your particular web application. Thus, if
	you include all of the required library classes in one of these places (be
	sure to check licenses for redistribution rights for any third party libraries
	you utilize), you will simplify the installation of your web application --
	no adjustment to the system class path (or installation of global library
	files in your server) will be necessary.</p>

	<p>Much of this information was extracted from Chapter 9 of the Servlet
	API Specification, version 2.3, which you should consult for more details.</p>

	</section>


	<section name="Shared Library Files">

	<p>Like most servlet containers, Tomcat 5 also supports mechanisms to install
	library JAR files (or unpacked classes) once, and make them visible to all
	installed web applications (without having to be included inside the web
	application itself. The details of how Tomcat locates and shares such
	classes are described in the
	<a href="../class-loader-howto.html">Class Loader HOW-TO</a> documentation.
	For the purposes of our discussion, there are two locations that are commonly
	used within a Tomcat 5 installation for shared code:</p>
	<ul>
	<li><strong>$CATALINA_HOME/common/lib</strong> - JAR files placed here are
	visible both to web applications and internal Tomcat code. This is a
	good place to put JDBC drivers that are required for both your application
	and internal Tomcat use (such as for a JDBCRealm).
	<br/><br/></li>
	<li><strong>$CATALINA_HOME/shared/lib</strong> - JAR files placed here are
	visible to all web applications, but not to internal Tomcat code. This
	is the right place for shared libraries that are specific to your
	application.<br/><br/></li>
	</ul>

	<p>Out of the box, a standard Tomcat 5 installation includes a variety
	of pre-installed shared library files, including:</p>
	<ul>
	<li>The <em>Servlet 2.4</em> and <em>JSP 2.0</em> APIs that are fundamental
	to writing servlets and JavaServer Pages.<br/><br/></li>
	<li>An <em>XML Parser</em> compliant with the JAXP (version 1.2) APIs, so
	your application can perform DOM-based or SAX-based processing of
	XML documents.<br/><br/></li>
	</ul>

	</section>


	<section name="Web Application Deployment Descriptor">

	<blockquote><em>
	<p>The description below uses the variable name $CATALINA_HOME
	to refer to the directory into which you have installed Tomcat 5,
	and is the base directory against which most relative paths are
	resolved. However, if you have configured Tomcat 5 for multiple
	instances by setting a CATALINA_BASE directory, you should use
	$CATALINA_BASE instead of $CATALINA_HOME for each of these
	references.</p>
	</em></blockquote>

	<p>As mentioned above, the <code>/WEB-INF/web.xml</code> file contains the
	Web Application Deployment Descriptor for your application. As the filename
	extension implies, this file is an XML document, and defines everything about
	your application that a server needs to know (except the <em>context path</em>,
	which is assigned by the system administrator when the application is
	deployed).</p>

	<p>The complete syntax and semantics for the deployment descriptor is defined
	in Chapter 13 of the Servlet API Specification, version 2.3. Over time, it
	is expected that development tools will be provided that create and edit the
	deployment descriptor for you. In the meantime, to provide a starting point,
	a <a href="web.xml.txt" target="_new">basic web.xml file</a>
	is provided. This file includes comments that describe the purpose of each
	included element.</p>

	<p><strong>NOTE</strong> - The Servlet Specification includes a Document
	Type Descriptor (DTD) for the web application deployment descriptor, and
	Tomcat 5 enforces the rules defined here when processing your application's
	<code>/WEB-INF/web.xml</code> file. In particular, you <strong>must</strong>
	enter your descriptor elements (such as <code><filter></code>,
	<code><servlet></code>, and <code><servlet-mapping></code> in
	the order defined by the DTD (see Section 13.3).</p>

	</section>


	<section name="Tomcat Context Descriptor">

	<blockquote><em>
	<p>The description below uses the variable name $CATALINA_HOME
	to refer to the directory into which you have installed Tomcat 5,
	and is the base directory against which most relative paths are
	resolved. However, if you have configured Tomcat 5 for multiple
	instances by setting a CATALINA_BASE directory, you should use
	$CATALINA_BASE instead of $CATALINA_HOME for each of these
	references.</p>
	</em></blockquote>

	<p>A /META-INF/context.xml file can be used to define Tomcat specific
	configuration options, such as loggers, data sources, session manager
	configuration and more. This XML file must contain one Context element, which
	will be considered as if it was the child of the Host element corresponding
	to the Host to which the The Tomcat configuration documentation contains
	information on the Context element.</p>

	</section>


	<section name="Deployment With Tomcat 5">

	<p>In order to be executed, a web application must be deployed on
	a servlet container. This is true even during development.
	We will describe using Tomcat 5 to provide the execution environment.
	A web application can be deployed in Tomcat by one of the following
	approaches:</p>
	<ul>
	<li><em>Copy unpacked directory hierarchy into a subdirectory in directory
	<code>$CATALINA_HOME/webapps/</code></em>. Tomcat will assign a
	context path to your application based on the subdirectory name you
	choose. We will use this technique in the <code>build.xml</code>
	file that we construct, because it is the quickest and easiest approach
	during development. Be sure to restart Tomcat after installing or
	updating your application.
	<br/><br/></li>
	<li><em>Copy the web application archive file into directory
	<code>$CATALINA_HOME/webapps/</code></em>. When Tomcat is started, it will
	automatically expand the web application archive file into its unpacked
	form, and execute the application that way. This approach would typically
	be used to install an additional application, provided by a third party
	vendor or by your internal development staff, into an existing
	Tomcat installation. <strong>NOTE</strong> - If you use this approach,
	and wish to update your application later, you must both replace the
	web application archive file <strong>AND</strong> delete the expanded
	directory that Tomcat created, and then restart Tomcat, in order to reflect
	your changes.
	<br/><br/></li>
	<li><em>Use the Tomcat 5 "Manager" web application to deploy and undeploy
	web applications</em>. Tomcat 5 includes a web application, deployed
	by default on context path <code>/manager</code>, that allows you to
	deploy and undeploy applications on a running Tomcat server without
	restarting it. See the administrator documentation (TODO: hyperlink)
	for more information on using the Manager web application.<br/><br/></li>
	<li><em>Use "Manager" Ant Tasks In Your Build Script</em>. Tomcat 5
	includes a set of custom task definitions for the <code>Ant</code>
	build tool that allow you to automate the execution of commands to the
	"Manager" web application. These tasks are used in the Tomcat deployer.
	<br/><br/></li>
	<li><em>Use the Tomcat Deployer</em>. Tomcat 5 includes a packaged tool
	bundling the Ant tasks, and can be used to automatically precompile JSPs
	which are part of the web application before deployment to the server.
	<br/><br/></li>
	</ul>

	<p>Deploying your app on other servlet containers will be specific to each
	container, but all containers compatible with the Servlet API Specification
	(version 2.2 or later) are required to accept a web application archive file.
	Note that other containers are <strong>NOT</strong> required to accept an
	unpacked directory structure (as Tomcat does), or to provide mechanisms for
	shared library files, but these features are commonly available.</p>

	</section>


	</body>
	</document>