Apache Tomcat Maven Plugin

Overview

The Apache Tomcat Maven Plugin provides goals to manipulate WAR projects within the Apache Tomcat servlet container. It supports:

Running web applications with an embedded Tomcat server
Deploying/undeploying web applications to a running Tomcat server
Creating self-contained executable WAR/JAR files with embedded Tomcat

The plugin supports Tomcat 9, Tomcat 10, and Tomcat 11.

Prerequisites

Java 8 or higher
Maven 3.8.1 or higher

Build

Edit the main pom.xml to set the main which should correspond to the version of Apache Tomcat that is going to be used.

./build.sh

Override default ports for integration tests:

./build.sh -Dits.http.port=8080 -Dits.ajp.port=8009

Basic Usage

Add the plugin to your pom.xml:

<plugin>
  <groupId>org.apache.tomcat.maven</groupId>
  <artifactId>tomcat-maven-plugin</artifactId>
  <version>${project.version}</version>
</plugin>

Common Goals

Run Goals

run - Start Tomcat and run your web application:

mvn tomcat:run

run-war - Run the current project as a packaged web application:

mvn tomcat:run-war

exec-war - Create a self-executable JAR file with embedded Tomcat:

mvn tomcat:exec-war

standalone-war - Create an executable WAR file with embedded Tomcat:

mvn tomcat:standalone-war

shutdown - Shut down all embedded Tomcat servers:

mvn tomcat:shutdown

Run Goals (No Lifecycle Forking)

The following goals are similar to the above but don't fork the Maven lifecycle:

run-war-only - Run the current project as a packaged web application without forking the package phase:

mvn tomcat:run-war-only

exec-war-only - Create a self-executable JAR file without forking the package phase:

mvn tomcat:exec-war-only

standalone-war-only - Create an executable WAR file without forking the package phase:

mvn tomcat:standalone-war-only

Deploy Goals

deploy - Deploy a WAR to Tomcat:

mvn tomcat:deploy

undeploy - Undeploy a WAR from Tomcat:

mvn tomcat:undeploy

redeploy - Redeploy an existing WAR:

mvn tomcat:redeploy

deploy-only - Deploy a WAR to Tomcat without forking the package lifecycle:

mvn tomcat:deploy-only

redeploy-only - Redeploy a WAR without forking the package lifecycle:

mvn tomcat:redeploy-only

Container Goals

list - List all deployed applications:

mvn tomcat:list

serverinfo - Get server information:

mvn tomcat:serverinfo

resources - List JNDI resources:

mvn tomcat:resources

Context Goals

reload - Reload a web application:

mvn tomcat:reload

sessions - List session information for a web application:

mvn tomcat:sessions

start - Start a web application:

mvn tomcat:start

stop - Stop a web application:

mvn tomcat:stop

wait - Wait for a specific webapp to become available:

mvn tomcat:wait

Configuration

Deploy to Tomcat

Configure server credentials in ~/.m2/settings.xml:

<settings>
  <servers>
    <server>
      <id>tomcat</id>
      <username>admin</username>
      <password>password</password>
    </server>
  </servers>
</settings>

Configure the plugin in your pom.xml:

<plugin>
  <groupId>org.apache.tomcat.maven</groupId>
  <artifactId>tomcat-maven-plugin</artifactId>
  <version>${project.version}</version>
  <configuration>
    <url>http://localhost:8080/manager/text</url>
    <server>tomcat</server>
    <path>/myapp</path>
  </configuration>
</plugin>

Run with Custom Port

Configure custom HTTP port in your pom.xml:

<plugin>
  <groupId>org.apache.tomcat.maven</groupId>
  <artifactId>tomcat-maven-plugin</artifactId>
  <version>${project.version}</version>
  <configuration>
    <port>9090</port>
    <path>/</path>
  </configuration>
</plugin>

Snapshots Deployment

To deploy a snapshot version to https://repository.apache.org/content/repositories/snapshots/, you must run:

mvn clean deploy

Note you need some configuration in ~/.m2/settings.xml:

<server>
  <id>apache.snapshots.https</id>
  <username>your asf id</username>
  <password>your asf password</password>
</server>

NOTE: A Jenkins job deploys SNAPSHOT automatically https://builds.apache.org/job/TomcatMavenPlugin/. So no real need to deploy manually, just commit and Jenkins will do the job for you.

Site Deployment

Checkstyle: this project uses the Apache Maven checkstyle configuration for IDE code style files. See http://maven.apache.org/developers/committer-environment.html.

Site: to test site generation, just run mvn site. If you want more reporting (javadoc, pmd, checkstyle, jxr, changelog from jira entries), use mvn site -Preporting.

To deploy site, use:

mvn clean site-deploy scm-publish:publish-scm -Dusername=$svnuid -Dpassword=$svnpwd -Preporting

The site will be deployed to http://tomcat.apache.org/maven-plugin-trunk ($svnuid is your asf id, $svnpwd is your asf password).

When releasing, deploy with -Psite-release.

Releasing

For release, your ~/.m2/settings.xml must contain:

<server>
  <id>apache.releases.https</id>
  <username>asf id</username>
  <password>asf password</password>
</server>

And run:

mvn release:prepare release:perform -Dusername= -Dpassword=

(username/password are your Apache svn authz)

Test Staged Tomcat Artifacts

To test staging artifacts for a vote process:

Activate a profile: tc-staging
Pass staging repository as parameter: -DtcStagedReleaseUrl=
Pass Tomcat version as parameter: -DtomcatVersion=

Examples

Example 1: Simple WAR Project

Create a simple WAR project and run it with Tomcat:

mkdir -p /tmp/tomcat-test
cd /tmp/tomcat-test

cat > pom.xml << 'EOF'
<?xml version="1.0" encoding="UTF-8"?>
<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.example</groupId>
    <artifactId>simple-webapp</artifactId>
    <version>1.0-SNAPSHOT</version>
    <packaging>war</packaging>
    
    <dependencies>
        <dependency>
            <groupId>javax.servlet</groupId>
            <artifactId>javax.servlet-api</artifactId>
            <version>4.0.1</version>
            <scope>provided</scope>
        </dependency>
    </dependencies>
    
    <build>
        <plugins>
            <plugin>
                <groupId>org.apache.tomcat.maven</groupId>
                <artifactId>tomcat-maven-plugin</artifactId>
                <version>${project.version}</version>
            </plugin>
        </plugins>
    </build>
</project>
EOF

mkdir -p src/main/webapp/WEB-INF
cat > src/main/webapp/index.jsp << 'EOF'
<!DOCTYPE html>
<html>
<head><title>Test App</title></head>
<body><h1>Hello from Tomcat!</h1></body>
</html>
EOF

# Run the application
mvn tomcat:run

# In another terminal, test it:
curl http://localhost:8080/simple-webapp-1.0-SNAPSHOT/

Example 2: Deploy to Remote Tomcat

mkdir -p /tmp/tomcat-remote
cd /tmp/tomcat-remote

cat > pom.xml << 'EOF'
<?xml version="1.0" encoding="UTF-8"?>
<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.example</groupId>
    <artifactId>remote-deploy</artifactId>
    <version>1.0-SNAPSHOT</version>
    <packaging>war</packaging>
    
    <build>
        <plugins>
            <plugin>
                <groupId>org.apache.tomcat.maven</groupId>
                <artifactId>tomcat-maven-plugin</artifactId>
                <version>${project.version}</version>
                <configuration>
                    <url>http://localhost:8080/manager/text</url>
                    <server>tomcat</server>
                    <path>/myapp</path>
                </configuration>
            </plugin>
        </plugins>
    </build>
</project>
EOF

mkdir -p src/main/webapp
cat > src/main/webapp/index.jsp << 'EOF'
<!DOCTYPE html>
<html>
<head><title>Remote Deploy Test</title></head>
<body><h1>Deployed to remote Tomcat!</h1></body>
</html>
EOF

# Deploy (requires Tomcat running with manager app)
mvn package tomcat:deploy

Mailing Lists

User List: users@tomcat.apache.org
Dev List: dev@tomcat.apache.org

License

Licensed under the Apache License, Version 2.0: http://www.apache.org/licenses/LICENSE-2.0