deploying a web application with maven into apache tomcat

[ad name=”breit”]

This article refers to Maven 2.1.0 and Apache Tomcat 6.0.18 on a Windows machine.

Auto-deploying a web application with Maven into Tomcat should be straightforward, but has some minor pitfalls. After I got it working today, I want to give a short summary of the required steps, since the “official documentation” leaves some open questions.

Let’s assume we want to deploy a web application with the name “foo” into Tomcat. To do automatic deployment of “foo” with Maven you have to enable the Tomcat targets. I’m using the codehaus.mojo Tomcat plug-in for that.

Open your pom.xml, locate the <plugins> tag and add the following code as an additional plug-in definition:

<plugin>
        <groupId>org.codehaus.mojo</groupId>
        <artifactId>tomcat-maven-plugin</artifactId>
        <configuration>
                <url>http://localhost:8080/manager</url>
	        <username>admin</username>
	        <password>admin</password>
                <path>/foo</path>
                <warFile>target/foor.war</warFile>
        </configuration>
</plugin>

The variables url, username and password must be set according to your Tomcat installation. The variable path ist the context root of the “foo” application and warFile is the location of your build target, wherever your build step creates the war file. I’m using a relative path here, because I call mvn from the project root directory.

For the automatic deployment of a war file you can use the follwoing targets:

• mvn tomcat:deploy
• mvn tomcat:redeploy
• mvn tomcat:undeploy

Actually, the redeploy target is sufficient, because it can also deploy when there is no existing web application. But the actual deployment step, which uploads the jar to the Tomcat server needs a lot of heap memory, so I increase the heap size that is available to Maven. Add the following line at the beginning of your mvn.bat (after all the @REM comments):

MAVEN_OPTS=-Xmx256M

Use any other value if you feel 256M is too small or too big.

Now the configuration is theoretically done and

mvn tomcat:deploy

can be executed. But if you are using JSF libraries, it may happen that only the first deployment works and any subsequent deployment fails. The reason is that some of the JSF related jars get locked by Tomcat and the undeployment remains unfinished. The server has to be stopped and the files manually removed. It seems that the XML parser inside Tomcat reads some DTD files from the jar files and does not properly release them, so the jars remain being used, even after stopping the application. They can only be deleted after stopping the whole Tomcat server. As a workaround I wrote a script that wraps these steps:

call E:\Apache\apache-tomcat-6.0.18\bin\shutdown.bat
 
ping -n 10 localhost
 
rmdir E:\Apache\apache-tomcat-6.0.18\webapps\foo /S /Q
del E:\Apache\apache-tomcat-6.0.18\webapps\foo.war /Q
 
call E:\Apache\apache-tomcat-6.0.18\bin\startup.bat
 
mvn tomcat:redeploy

Save this snippet for instance as “deployfoo.bat”. If you wonder about the ping. This is, because the Windows CMD shell does not have a sleep or wait command, but it is important that the shutdown has finished before trying to delete the files. This would happen without it, becase shutdown.bat is called asynchonously, which is necessary, beause if the shutdown fails i.e. when Tomcat is not running, it would terminate the whole script, hence nothing gets deployed. That’s why we need a wait and Ping can do that.

That’s basically all. Now you can call “deployfoo.bat” for deploying the foo web application.