This is an automated email from the ASF dual-hosted git repository.
remm pushed a commit to branch trunk
in repository https://gitbox.apache.org/repos/asf/tomcat-maven-plugin.git
The following commit(s) were added to refs/heads/trunk by this push:
new 5d8ebce Add READNE.md (generated ...)
5d8ebce is described below
commit 5d8ebce36a6ea4a875850f26a711c32dbb08ec77
Author: remm <[email protected]>
AuthorDate: Thu Apr 9 11:53:43 2026 +0200
Add READNE.md (generated ...)
---
README.md | 342 ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
1 file changed, 342 insertions(+)
diff --git a/README.md b/README.md
new file mode 100644
index 0000000..d840d64
--- /dev/null
+++ b/README.md
@@ -0,0 +1,342 @@
+# Apache Tomcat Maven Plugin
+
+[](https://builds.apache.org/job/TomcatMavenPlugin/)
+
+## 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
+
+## Basic Usage
+
+Add the plugin to your `pom.xml`:
+
+```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:
+
+```bash
+mvn tomcat:run
+```
+
+### Deploy Goals
+
+**deploy** - Deploy a WAR to Tomcat:
+
+```bash
+mvn package tomcat:deploy
+```
+
+**undeploy** - Undeploy a WAR from Tomcat:
+
+```bash
+mvn tomcat:undeploy
+```
+
+**redeploy** - Redeploy an existing WAR:
+
+```bash
+mvn package tomcat:redeploy
+```
+
+### Container Goals
+
+**list** - List all deployed applications:
+
+```bash
+mvn tomcat:list
+```
+
+**info** - Get server information:
+
+```bash
+mvn tomcat:info
+```
+
+**resources** - List JNDI resources:
+
+```bash
+mvn tomcat:resources
+```
+
+**roles** - List security roles:
+
+```bash
+mvn tomcat:roles
+```
+
+## Configuration
+
+### Deploy to Tomcat
+
+Configure server credentials in `~/.m2/settings.xml`:
+
+```xml
+<settings>
+ <servers>
+ <server>
+ <id>tomcat</id>
+ <username>admin</username>
+ <password>password</password>
+ </server>
+ </servers>
+</settings>
+```
+
+Configure the plugin in your `pom.xml`:
+
+```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`:
+
+```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>
+```
+
+## Build
+
+```bash
+mvn clean install
+```
+
+To run integration tests:
+
+```bash
+mvn clean install -Prun-its
+```
+
+Override default ports for integration tests:
+
+```bash
+mvn clean install -Prun-its -Dits.http.port=8080 -Dits.ajp.port=8009
+```
+
+## Snapshots Deployment
+
+To deploy a snapshot version to
https://repository.apache.org/content/repositories/snapshots/, you must run:
+
+```bash
+mvn clean deploy
+```
+
+Note you need some configuration in `~/.m2/settings.xml`:
+
+```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:
+
+```bash
+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:
+
+```xml
+<server>
+ <id>apache.releases.https</id>
+ <username>asf id</username>
+ <password>asf password</password>
+</server>
+```
+
+And run:
+
+```bash
+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=` (for Tomcat 10/11) or
`-Dtomcat9Version=` (for Tomcat 9)
+
+Sample for Tomcat 10/11 artifacts:
+
+```bash
+mvn clean install -Prun-its -Ptc-staging
-DtcStagedReleaseUrl=stagingrepositoryurl -DtomcatVersion=11.0.21
+```
+
+Sample for Tomcat 9 artifacts:
+
+```bash
+mvn clean install -Prun-its -Ptc-staging
-DtcStagedReleaseUrl=stagingrepositoryurl -Dtomcat9Version=9.0.117
+```
+
+## Examples
+
+### Example 1: Simple WAR Project
+
+Create a simple WAR project and run it with Tomcat:
+
+```bash
+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
+
+```bash
+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: [email protected]
+- Dev List: [email protected]
+
+## License
+
+Licensed under the Apache License, Version 2.0:
http://www.apache.org/licenses/LICENSE-2.0
\ No newline at end of file
---------------------------------------------------------------------
To unsubscribe, e-mail: [email protected]
For additional commands, e-mail: [email protected]
