Configuring the Maven Tomcat Plugin

My last blog explained the relationships between Mavan life-cycles, build phases and goals from a height of about 3 miles. In explaining Maven’s goals I mentioned the tomcat:redeploy goal without really defining where it came from. Well, the answer is that the tomcat:redeploy goal isn’t a default goal or part of the default Maven installation, it’s part of the tomcat-maven-plugin. This plugin comes with several useful goals that allow you to manipulate Tomcat as part of your build process - the big idea here is that Tomcat can automatically become part of your extended build process, a process that would look something like this:

1. compile the source code
2. perform unit tests
3. build WAR file
4. automatically deploy WAR file
5. run integration tests

...allowing you to both unit test and integration test your code automatically.

This blog covers using version 1 of the tomcat-maven-plugin details of which are available from codehause. Since I started using this plugin some time ago, the project has moved under the Apache umbrella of the Tomcat project, where version 2 is currently under development and is currently available as a beta release.

Setting up the Maven Tomcat plugin consists of three steps.

1. Setup a Tomcat manager account.
2. Add the manager credentials to your settings.xml
3. Add the Maven Tomcat plugin to your POM file.

Setup a Tomcat Manager Account

Setting up a Tomcat manager account is a prerequisite when it comes to using the Tomcat Maven Plugin. There’s been a huge amount written about this on the web, so I’m not going to go into too much detail, except to say that the config varies between Tomcat versions. In Tomcat 7 you need to update your Tomcat configuration’s tomcat_users.xml file adding something like this:¹

<?xml version="1.0" encoding="UTF-8"?>
<tomcat-users>
 <role rolename="manager-gui"/>
 <role rolename="manager-script"/>
    <user username="admin" password="password" roles="manager-gui, manager-script"/>
</tomcat-users>

Assuming that you’re running locally with default security settings, then you can test this out by typing: http://localhost:8080/manager in to your browser. You’ll then be presented with the default security challenge dialogue and you’ll be able to login with your new credentials...

…and see your server’s manager page.

Add the manager credentials to your settings.xml

The next step is to tell Maven about your Tomcat manager’s user name and password. To do this you need to add something like this:

    <server>
      <id>myserver</id>
      <username>admin</username>
      <password>password</password>
    </server>

...to the <servers> section your Maven settings.xml file. Obviously the username and password must match those in your tomcat-users.xml file. Note the id tag, you’ll see this again in the next section.

Add the Maven Tomcat plug in to your POM file

This final step gets to the heart of the matter. The Maven Tomcat Plugin is configured by adding the following XML to the <plugins> section of your project’s POM file:

    <plugin>
        <groupId>org.codehaus.mojo</groupId>
        <artifactId>tomcat-maven-plugin</artifactId>
        <version>1.1</version>
        <configuration>
            <server>myserver</server>
            <url>http://localhost:8080/manager/text</url> 
        </configuration>
    </plugin>

This is really straight forward; however, there are a couple of points to note. Firstly, in the <configuration> section, you’ll see the server id of myserver. This must match the server id that you added to your settings.xml file in the previous section. Secondly, the server’s url setting seems, for no given reason, to have to end with "/manager/text", for example: "http://localhost:8080/manager/text". I guess that this is explained somewhere, but I can’t find it - all I know is that it just works.

You can now start your server and run a Maven build using the "mvn install tomcat:deploy" command. Once installed, switch to the "tomcat:redeploy" goal.

---

¹ The main difference between Tomcat 7 and previous versions is that in Tomcat 7 the manager role has been split into several distinct sub-roles. Therefore in Tomcat 7 you need to specify roles like manager-gui etc, whereas in previous versions the role of manager would suffice.