I have been trying to use the catalina "deploy" ant task to deploy my
web app to Tomcat 5.0 from a local directory structure (not a war
file). Unfortunately, this proved rather difficult, as this task is not
documented very well at present. After reading various bits of
documentation and the source code of the ant task, I have finally
figured out how to do it, and in the process learned several other
undocumented facts. I thought it would be a good idea to share my
findings with the Tomcat community.

In short, the key to deploying a web app from a local directory *or* a
local war file is to use the "localWar" attribute of the deploy task,
not the "war" attribute. The attribute value should be the path to the
directory or the war file, prefixed with "file://", for example:

  localWar="file://${build.home}"

The "war" attribute of the deploy task can only be used with a war file,
not a directory. If you use this attribute, the deploy task uploads the
contents of the war file to the server. In other words, the war file
will be *copied* to the server. (If you just want your server to
directly use the war file at the given path, you should use the
"localWar" attribute, not the "war" attribute.) Also, note the
following facts about the value of the "war" attribute:

  - It can start with "file://", but (at least) on Windows, appears to
require a third slash in the prefix, for example: "file:///c:/blah/foo.war".

  - It can be a simple path, for example, "c:/blah/foo.war".

  - In either case (using the "file:" syntax or not), on Windows, the
path can use backslashes instead of forward slashes, or a mix, for
example, "file:///c:\blah/foo.war".


Here are some more details, particularly regarding the documentation.

The javadoc for the org.apache.catalina.ant package contains some
documentation about the ant tasks it defines:

 
http://jakarta.apache.org/tomcat/tomcat-5.0-doc/catalina/docs/api/org/apache/catalina/ant/package-summary.html

Unfortunately, this summary does not mention the "localWar" attribute,
and incorrectly states that the "war" attribute can be used with a
directory.

The javadoc for the deploy task is here:

 
http://jakarta.apache.org/tomcat/tomcat-5.0-doc/catalina/docs/api/org/apache/catalina/ant/DeployTask.html

It does mention both the "localWar" and "war" attributes, but suggests
that these can only be used to deploy a war file -- it doesn't mention
deploying from a directory.

Some key documentation about the Tomcat manager protocol is here:

  http://jakarta.apache.org/tomcat/tomcat-5.0-doc/manager-howto.html

The section "Deploy A New Application Remotely" describes the war upload
protocol. This protocol is used by the "deploy" task when the "war"
attribute is specified. In this case, the war file is uploaded using
HTTP PUT.

The sub-section "Deploy A New Application from a Local Path", "Install a
Directory or WAR by URL" describes the protocol used by the "deploy"
task when the "localWar" attribute is specified. In this case, the path
to the local directory or war file is given by the "war" parameter in
the URL using HTTP GET.  Yes, it is confusing that the "war" URL
parameter is used when the deploy task specifies the "localWar"
attribute, but not when it specifies the "war" attribute.

Unfortunately, the section "Executing Manager Commands With Ant" doesn't
really help understand the deploy task. In fact, the example deploy
task in that section appears to be incorrect, as it specifies a
directory using the "war" attribute, which doesn't work -- the
"localWar" attribute must be used for a directory.

I hope some of you will find this information helpful.

- Patrick



---------------------------------------------------------------------
To unsubscribe, e-mail: tomcat-user-unsubscribe@(protected)
For additional commands, e-mail: tomcat-user-help@(protected)