Tomcat

Effortless Deployment: Your Guide to the Tomcat Maven Plugin

Leave a comment

As a developer, I’m always looking for ways to streamline my workflow, especially when it comes to deploying applications. If you’re working with Maven and Tomcat, the Tomcat Maven Plugin is an absolute game-changer. It allows you to deploy, start, stop, and even redeploy your web applications directly from your Maven build, eliminating the need for manual server interactions. In this post, we’ll dive deep into using this powerful plugin, complete with practical examples to get you up and running quickly.

Let’s get started!

What is the Tomcat Maven Plugin?

The Tomcat Maven Plugin is a Maven plugin that provides goals for running and deploying web applications to an embedded or standalone Tomcat server. It simplifies the development and testing cycle by allowing you to manage your application’s lifecycle within your Maven project.

Prerequisites

Before we jump into the configuration, make sure you have the following installed:

  • JDK (Java Development Kit)
  • Apache Maven
  • A Java web application project (WAR file packaging)

Adding the Plugin to Your pom.xml

The first step is to add the Tomcat Maven Plugin to your project’s pom.xml file. You’ll typically place it within the <build><plugins></plugins></build> section.

1. Basic Configuration

For most scenarios, the following basic configuration will suffice:

<build>
    <plugins>
        <plugin>
            <groupId>org.apache.tomcat.maven</groupId>
            <artifactId>tomcat7-maven-plugin</artifactId>
            <version>2.2</version>
            <configuration>
                <url>http://localhost:8080/manager/text</url>
                <server>TomcatServer</server>
                <path>/mywebapp</path>
            </configuration>
        </plugin>
    </plugins>
</build>

Let’s break down the key elements of this configuration:

  • groupId: org.apache.tomcat.maven (Identifies the plugin’s organization).
  • artifactId: tomcat7-maven-plugin (Specifies the plugin for Tomcat 7. For Tomcat 8/9, use tomcat8-maven-plugin or tomcat9-maven-plugin).
  • version: 2.2 (The version of the plugin. Always refer to the latest stable version).
  • configuration: This section holds the plugin-specific settings.
    • url: The URL of your Tomcat Manager application. This is crucial for remote deployments. The /manager/text path is commonly used for programmatic interaction.
    • server: This refers to a server entry defined in your Maven settings.xml (more on this below). It’s used for authentication.
    • path: The context path under which your application will be deployed (e.g., http://localhost:8080/mywebapp).

2. Configuring Tomcat Manager Credentials in settings.xml

For the Tomcat Maven Plugin to interact with your Tomcat server, it needs authentication credentials for the Tomcat Manager. It’s best practice to keep these credentials out of your pom.xml and instead configure them in your Maven settings.xml file. This file is typically located at ~/.m2/settings.xml (for Linux/macOS) or C:\Users\YOUR_USERNAME\.m2\settings.xml (for Windows).

Add the following entry to your settings.xml:

<settings>
    <servers>
        <server>
            <id>TomcatServer</id>
            <username>admin</username>
            <password>your_manager_password</password>
        </server>
    </servers>
</settings>

Important:

  • The id in the entry (TomcatServer in this example) must match the element in your pom.xml plugin configuration.
  • Make sure your Tomcat Manager application is configured with a user that has the manager-gui or manager-script role. You can do this in your Tomcat’s conf/tomcat-users.xml file.
<!-- For manager-gui role (access to GUI manager)and  manager-script role (programmatic access, commonly used by maven plugin) -->
<user username="admin" password="your_manager_password" roles="manager-gui,manager-script"/>

Common Goals and Usage

Once configured, you can use various goals provided by the Tomcat Maven Plugin.

1. tomcat7:run (For development – embedded Tomcat)

This goal starts an embedded Tomcat server and deploys your application to it. It’s fantastic for quick local development and testing without having to set up a separate Tomcat instance.

mvn tomcat7:run

Your application will typically be accessible at http://localhost:8080/your_context_path.

You can also configure the port:

<plugin>
    <groupId>org.apache.tomcat.maven</groupId>
    <artifactId>tomcat7-maven-plugin</artifactId>
    <version>2.2</version>
    <configuration>
        <port>9090</port>
        <url>http://localhost:8080/manager/text</url>
        <server>TomcatServer</server>
        <path>/mywebapp</path>
    </configuration>
</plugin>

Then run with mvn tomcat7:run, and it will be on port 9090.

2. tomcat7:deploy (Deploy to standalone Tomcat)

This goal deploys your compiled WAR file to a running standalone Tomcat server via the Manager application.

mvn tomcat7:deploy

Before running this, ensure your Tomcat server is running and the Manager application is accessible at the configured URL.

3. tomcat7:undeploy (Remove from standalone Tomcat)

If you need to remove your application from Tomcat, use the undeploy goal.

mvn tomcat7:undeploy

4. tomcat7:redeploy (Update and restart)

This is one of the most useful goals for continuous development. It undeploys your existing application, deploys the new version, and restarts it – all in one command.

mvn tomcat7:redeploy

5. tomcat7:start and tomcat7:stop

While deploy and undeploy handle the application lifecycle, you might sometimes need to explicitly start or stop the application *after* it’s deployed or for an already deployed application.

mvn tomcat7:start
mvn tomcat7:stop

Example Web Application Structure

Let’s assume you have a basic Maven web application project with the following structure:

mywebapp/
├── pom.xml
└── src/
    └── main/
        └── webapp/
            ├── WEB-INF/
            │   └── web.xml
            └── index.jsp

And a simple index.jsp:

<html>
<body>
    <h2>Hello from ankurm.com's Maven Tomcat Plugin Example!</h2>
    <% out.println("Current Time: " + new java.util.Date()); %>
</body>
</html>

A Complete pom.xml Example

Here’s a more complete pom.xml including the plugin and standard web app configurations:

<project xmlns="http://maven.apache.org/POM/4.0.0"
         xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
         xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 http://maven.apache.org/xsd/maven-4.0.0.xsd">
    <modelVersion>4.0.0</modelVersion>
    <groupId>com.ankurm.webapp</groupId>
    <artifactId>mywebapp</artifactId>
    <version>1.0-SNAPSHOT</version>
    <packaging>war</packaging>
    <name>ankurm.com Tomcat Maven Plugin Example</name>
    <properties>
        <maven.compiler.source>1.8</maven.compiler.source>
        <maven.compiler.target>1.8</maven.compiler.target>
        <failOnMissingWebXml>false</failOnMissingWebXml>
    </properties>
    <dependencies>
        <!-- Servlet API for JSP/Servlets -->
        <dependency>
            <groupId>javax.servlet</groupId>
            <artifactId>javax.servlet-api</artifactId>
            <version>3.1.0</version>
            <scope>provided</scope>
        </dependency>
        <dependency>
            <groupId>javax.servlet.jsp</groupId>
            <artifactId>javax.servlet.jsp-api</artifactId>
            <version>2.3.1</version>
            <scope>provided</scope>
        </dependency>
    </dependencies>
    <build>
        <finalName>mywebapp</finalName> <!-- Name of the WAR file and default context path prefix -->
        <plugins>
            <plugin>
                <groupId>org.apache.maven.plugins</groupId>
                <artifactId>maven-compiler-plugin</artifactId>
                <version>3.8.1</version>
                <configuration>
                    <source>${maven.compiler.source}</source>
                    <target>${maven.compiler.target}</target>
                </configuration>
            </plugin>
            <!-- Tomcat Maven Plugin Configuration -->
            <plugin>
                <groupId>org.apache.tomcat.maven</groupId>
                <artifactId>tomcat7-maven-plugin</artifactId>
                <version>2.2</version> <!-- Use tomcat8-maven-plugin or tomcat9-maven-plugin for newer versions -->
                <configuration>
                    <!-- The URL for the Tomcat Manager application -->
                    <url>http://localhost:8080/manager/text</url>
                    <!-- Server ID defined in your ~/.m2/settings.xml for authentication -->
                    <server>TomcatServer</server>
                    <!-- The desired context path for your application -->
                    <path>/ankurm-app</path>
                    <!-- Optional: Port for embedded Tomcat (tomcat7:run) -->
                    <port>8080</port>
                    <!-- Optional: If you want to skip WAR file packaging before deploy -->
                    <update>true</update> <!-- Useful for redeploying without undeploying first -->
                </configuration>
            </plugin>
        </plugins>
    </build>
</project>

In this example, the application will be accessible at http://localhost:8080/ankurm-app when deployed.

Troubleshooting Common Issues

  • 401 Unauthorized or Permission Denied:
    • Double-check that the server ID in your pom.xml matches the id in settings.xml.
    • Verify the username and password in settings.xml.
    • Ensure the user in tomcat-users.xml has the manager-script role (or manager-gui in some cases for older setups).
    • Confirm the Tomcat Manager application is running and accessible at the specified url.
  • No goals have been specified for this build.: You forgot to specify a goal, e.g., mvn tomcat7:run or mvn tomcat7:deploy.
  • Application Not Loading (404 Error):
    • Check the path configuration in your pom.xml matches the URL you’re trying to access.
    • Ensure the web application (WAR file) was successfully built and deployed. Look for “BUILD SUCCESS” in the Maven output.
    • If using tomcat7:run, make sure no other process is using port 8080 (or your configured port).
  • Plugin Not Found: Verify the groupId, artifactId, and version of the plugin are correct and that Maven can access the central repository or your configured mirror.

Conclusion

The Tomcat Maven Plugin is an incredibly useful tool for any Java web developer working with Maven and Tomcat. It simplifies the deployment process, allowing you to focus more on coding and less on server management. By leveraging goals like run, deploy, and redeploy, you can significantly speed up your development cycle and achieve a more efficient workflow. Bookmark this guide on ankurm.com for your future deployments, and happy coding!

Do you have any tips or tricks for using the Tomcat Maven Plugin? Share them in the comments below!

Leave a Reply

This site uses Akismet to reduce spam. Learn how your comment data is processed.