You are viewing a plain text version of this content. The canonical link for it is here.
Posted to dev@tomcat.apache.org by re...@apache.org on 2003/05/12 23:30:39 UTC
cvs commit: jakarta-tomcat-catalina/webapps/docs manager-howto.xml
remm 2003/05/12 14:30:39
Modified: webapps/docs manager-howto.xml
Log:
- Update the manager docs according to the new proposed behavior
(reverting is easy :) ).
Revision Changes Path
1.5 +52 -76 jakarta-tomcat-catalina/webapps/docs/manager-howto.xml
Index: manager-howto.xml
===================================================================
RCS file: /home/cvs/jakarta-tomcat-catalina/webapps/docs/manager-howto.xml,v
retrieving revision 1.4
retrieving revision 1.5
diff -u -r1.4 -r1.5
--- manager-howto.xml 15 Jan 2003 03:40:43 -0000 1.4
+++ manager-howto.xml 12 May 2003 21:30:39 -0000 1.5
@@ -21,12 +21,11 @@
Configuring Manager Application Access</a><br />
<a href="#Supported Manager Commands">Supported Manager Commands</a><br />
<blockquote>
-<a href="#Deploy A New Application">Deploy A New Application</a><br />
-<a href="#Install A New Application">Install A New Application</a><br />
+<a href="#Deploy A New Application Remotely">Deploy A New Application Remotely</a><br />
+<a href="#Deploy A New Application from a Local Path">Deploy A New Application from a Local Path</a><br />
<a href="#List Currently Deployed and Installed Applications">
List Currently Deployed and Installed Applications</a><br />
<a href="#Reload An Existing Application">Reload An Existing Application</a><br />
-<a href="#Remove an Existing Application">Remove an Existing Application</a><br />
<a href="#List OS and JVM Properties">List OS and JVM Properties</a><br />
<a href="#List Available Global JNDI Resources">
List Available Global JNDI Resources</a><br />
@@ -265,7 +264,7 @@
have been translated for your platform. The examples below show the English
version of the messages.</p>
-<subsection name="Deploy A New Application">
+<subsection name="Deploy A New Application Remotely">
<source>
http://localhost:8080/manager/deploy?path=/foo
@@ -280,10 +279,21 @@
later be undeployed (and the corresponding application directory removed)
by use of the <code>/undeploy</code>.</p>
-<p><strong>NOTE</strong> - Since this command requires an HTTP PUT request,
-it is usable only from tools (such as the custom Ant tasks described below).
-To install a new web application without copying, consider the
-<code>/install</code> command described below. This command is the logical
+<p>URL parameters include:
+<ul>
+<li><code>update</code>: When set to true, any existing update will be
+ undeployed first. The default value is set to false.</li>
+<li><code>tag</code>: Specifying a tag name, this allows associating the
+ deployed webapp with a version number. The application version can
+ be later redeployed when needed using only the tag.</li>
+<li><code>pause</code>: Pause webapps so that incoming connections are not lost
+ during an application update. This option is only used with the update
+ parameter, and its default is false. Note that a large amount of request
+ processors may be used if the amount of incoming requests is large.</li>
+</ul>
+</p>
+
+<p><strong>NOTE</strong> - This command is the logical
opposite of the <code>/undeploy</code> command.</p>
<p>If installation and startup is successful, you will receive a response
@@ -300,7 +310,10 @@
<p>The context paths for all currently running web applications must be
unique. Therefore, you must either remove or undeploy the existing web
application using this context path, or choose a different context path
- for the new one.</p>
+ for the new one. The <code>update</code> parameter may be specified as
+ a parameter on the URL, with a value of <code>true</code> to avoid this
+ error. In that case, an undeploy will be performed on an existing
+ application before performing the deployment.</p>
</blockquote></li>
<li><em>Encountered exception</em>
<blockquote>
@@ -324,7 +337,7 @@
</subsection>
-<subsection name="Install A New Application">
+<subsection name="Deploy A New Application from a Local Path">
<p>Install and start a new web application, attached to the specified context
<code>path</code> (which must not be in use by any other web application).
@@ -332,6 +345,17 @@
<p>There are a number of different ways the install command can be used.</p>
+<h3>Install a version of a previously deployed webapp</h3>
+
+<p>This can be used to deploy a previous version of a web applicaion, which
+has been deployed using the <code>tag</code> attribute. Note that the work
+directory for the manager webapp will contain the previously deployed WARs;
+removing it would make the deployment fail.
+<source>
+http://localhost:8080/manager/deploy?path=/footoo&tag=footag
+</source>
+</p>
+
<h3>Install a Directory or WAR by URL</h3>
<p>Install a web application directory or ".war" file located on the Tomcat
@@ -347,7 +371,7 @@
<code>/path/to/foo</code> on the Tomcat server is installed as the
web application context named <code>/footoo</code>.
<source>
-http://localhost:8080/manager/install?path=/footoo&war=file:/path/to/foo
+http://localhost:8080/manager/deploy?path=/footoo&war=file:/path/to/foo
</source>
</p>
@@ -357,7 +381,7 @@
so the context path defaults to the name of the web application archive
file without the ".war" extension.
<source>
-http://localhost:8080/manager/install?war=jar:file:/path/to/bar.war!/
+http://localhost:8080/manager/deploy?war=jar:file:/path/to/bar.war!/
</source>
</p>
@@ -373,7 +397,7 @@
that there is no <code>path</code> parameter so the context path defaults
to the name of the web application directory.
<source>
-http://localhost:8080/manager/install?war=foo
+http://localhost:8080/manager/deploy?war=foo
</source>
</p>
@@ -381,7 +405,7 @@
Host appBase directory on the Tomcat server is installed as the web
application context named <code>/bartoo</code>.
<source>
-http://localhost:8080/manager/install?path=/bartoo&war=bar.war
+http://localhost:8080/manager/deploy?path=/bartoo&war=bar.war
</source>
</p>
@@ -416,7 +440,7 @@
<p>Here is an example of installing an application using a Context
configuration ".xml" file.
<source>
-http://localhost:8080/manager/install?config=file:/path/context.xml
+http://localhost:8080/manager/deploy?config=file:/path/context.xml
</source>
</p>
@@ -424,7 +448,7 @@
configuration ".xml" file and a web application ".war" file located
on the server.
<source>
-http://localhost:8080/manager/install?config=file:/path/context.xml&war=jar:file:/path/bar.war!/
+http://localhost:8080/manager/deploy?config=file:/path/context.xml&war=jar:file:/path/bar.war!/
</source>
</p>
@@ -451,7 +475,7 @@
<p>If installation and startup is successful, you will receive a response
like this:</p>
<source>
-OK - Installed application at context path /foo
+OK - Deployed application at context path /foo
</source>
<p>Otherwise, the response will start with <code>FAIL</code> and include an
@@ -462,7 +486,10 @@
<p>The context paths for all currently running web applications must be
unique. Therefore, you must either remove or undeploy the existing web
application using this context path, or choose a different context path
- for the new one.</p>
+ for the new one. The <code>update</code> parameter may be specified as
+ a parameter on the URL, with a value of <code>true</code> to avoid this
+ error. In that case, an undeploy will be performed on an existing
+ application before performing the deployment.</p>
</blockquote></li>
<li><em>Document base does not exist or is not a readable directory</em>
<blockquote>
@@ -589,56 +616,6 @@
</subsection>
-<subsection name="Remove an Existing Application">
-
-<source>
-http://localhost:8080/manager/remove?path=/examples
-</source>
-
-<p><strong><font color="red">WARNING</font> - This command will delete the
-contents of the web application directory and/or ".war" file if it exists within
-the <code>appBase</code> directory (typically "webapps") for this virtual host
-</strong>. The web application temporary work directory is also deleted. If
-you simply want to take an application out of service, you should use the
-<code>/stop</code> command instead.</p>
-
-<p>Signal an existing application to gracefully shut itself down, and then
-remove it from Tomcat (which also makes this context path available for
-reuse later). This command is the logical opposite of the
-<code>/install</code> command.</p>
-
-<p>If this command succeeds, you will see a response like this:</p>
-<source>
-OK - Removed application at context path /examples
-</source>
-
-<p>Otherwise, the response will start with <code>FAIL</code> and include an
-error message. Possible causes for problems include:</p>
-<ul>
-<li><em>Encountered exception</em>
- <blockquote>
- <p>An exception was encountered trying to remove the web application.
- Check the Tomcat 4 logs for the details.</p>
- </blockquote></li>
-<li><em>Invalid context path was specified</em>
- <blockquote>
- <p>The context path must start with a slash character, unless you are
- referencing the ROOT web application -- in which case the context path
- must be a zero-length string.</p>
- </blockquote></li>
-<li><em>No context exists for path /foo</em>
- <blockquote>
- <p>There is no deployed or installed application on the context path
- that you specified.</p>
- </blockquote></li>
-<li><em>No context path was specified</em>
- <blockquote>
- The <code>path</code> parameter is required.
- </blockquote></li>
-</ul>
-
-</subsection>
-
<subsection name="List OS and JVM Properties">
<source>
@@ -881,8 +858,9 @@
<p><strong><font color="red">WARNING</font> - This command will
delete the contents of the web application directory if it exists within the
<code>appBase</code> directory (typically "webapps") for this virtual host
-</strong>. If you simply want to take an application out of service,
-you should use the <code>/stop</code> command instead.</p>
+</strong>. This will also delete the source .WAR if expanding occurred, as
+well as the XML Context definition. If you simply want to take an application
+out of service, you should use the <code>/stop</code> command instead.</p>
<p>Signal an existing application to gracefully shut itself down, and
remove it from Tomcat (which also makes this context path available for
@@ -968,10 +946,8 @@
<!-- Configure the custom Ant tasks for the Manager application -->
<taskdef name="deploy" classname="org.apache.catalina.ant.DeployTask"/>
- <taskdef name="install" classname="org.apache.catalina.ant.InstallTask"/>
<taskdef name="list" classname="org.apache.catalina.ant.ListTask"/>
<taskdef name="reload" classname="org.apache.catalina.ant.ReloadTask"/>
- <taskdef name="remove" classname="org.apache.catalina.ant.RemoveTask"/>
<taskdef name="resources" classname="org.apache.catalina.ant.ResourcesTask"/>
<taskdef name="roles" classname="org.apache.catalina.ant.RolesTask"/>
<taskdef name="start" classname="org.apache.catalina.ant.StartTask"/>
@@ -983,9 +959,9 @@
<!-- ... construct web application in ${build} subdirectory ... -->
</target>
- <target name="install" description="Install web application"
+ <target name="deploy" description="Install web application"
depends="compile">
- <install url="${url}" username="${username}" password="${password}"
+ <deploy url="${url}" username="${username}" password="${password}"
path="${path}" war="file://${build}"/>
</target>
@@ -995,7 +971,7 @@
path="${path}"/>
</target>
- <target name="remove" description="Remove web application">
+ <target name="undeploy" description="Remove web application">
<remove url="${url}" username="${username}" password="${password}"
path="${path}"/>
</target>
@@ -1004,7 +980,7 @@
</pre></td></tr>
</table>
-<p>Now, you can execute commands like <code>ant install</code> to install th
+<p>Now, you can execute commands like <code>ant deploy</code> to deploy the
applcation to a running instance of Tomcat, or <code>ant reload</code> to
tell Tomcat to reload it. Note also that most of the interesting values in
this <code>build.xml</code> file are defined as replaceable properties, so
---------------------------------------------------------------------
To unsubscribe, e-mail: tomcat-dev-unsubscribe@jakarta.apache.org
For additional commands, e-mail: tomcat-dev-help@jakarta.apache.org