If you enjoy subtle thrills like watching a server unpack a zip file then deploying a WAR to Tomcat with Maven is your kind of party. This guide walks through preparing a Java webapp, wiring up the Tomcat Maven plugin, building a WAR and deploying it either automatically or by hand. No smoke and mirrors, just useful commands and things to check when the manager sends you a passive aggressive error.

Prepare your Maven webapp

Start with a normal Maven web project. In your pom.xml set the packaging to war and keep your web sources under src/main/webapp. Add a standard web.xml if you need old school servlet configuration and declare any required dependencies in the pom so the WAR includes them.

• pom.xml: <packaging>war</packaging>
• Source layout: src/main/webapp for JSPs static assets and WEB-INF
• Dependencies: include servlet API as provided if Tomcat already supplies it

Add and configure the Tomcat Maven plugin

Edit pom.xml to include the Tomcat Maven plugin so Maven can talk to Tomcat manager. You must provide a manager URL and credentials for a user with the manager role on the Tomcat server. Please do not paste plain passwords in pom.xml like it is 2005.

Best practice for credentials

Put the server id and credentials in your ~/.m2/settings.xml and reference the server id from the pom. That keeps secrets out of version control and avoids awkward conversations with compliance.

<server>
  <id>tomcat-host</id>
  <username>deployuser</username>
  <password>REDACTED</password>
</server>

Build the WAR

Run the classic Maven combo to produce a clean WAR artifact.

mvn clean package

The WAR will appear in target/. That is the file you will either push with the plugin or copy into Tomcat's webapps folder like an analog hacker.

Deploy using the Tomcat Maven plugin

If you prefer automation invoke the plugin's deploy goal to upload the WAR to the Tomcat manager. If Tomcat gives you a manager role or credential error double check your server id mapping and the roles on the Tomcat user that you configured in tomcat-users.xml.

mvn tomcat7:deploy -DskipTests

If you need to redeploy an existing context use the redeploy goal or add the path parameter. The manager will reject uploads if the user lacks permissions so fix roles before blaming Maven.

Manual deploy to Tomcat webapps

If the plugin feels like modern alchemy then the boring reliable trick is to copy the WAR into TOMCAT_HOME/webapps. Tomcat will explode the archive into a folder and register the context. Restart Tomcat when a simple drop does not register the application.

1. Copy target/yourapp.war to $CATALINA_HOME/webapps
2. Watch the logs or tail logs/catalina.out
3. Visit http://your-server:8080/yourapp to confirm

Verify and troubleshoot deployment

When things go sideways the Tomcat logs are your best friend. Look for class loader errors missing classes or exceptions during context startup. Common issues and quick fixes follow.

Common problems

• Missing dependencies. Add them to the WAR or mark them provided if Tomcat supplies them.
• Context path collisions. Ensure the WAR name and context.xml do not conflict with another app.
• Manager permission errors. Confirm the user has manager script or manager gui roles depending on your plugin and Tomcat version.

Helpful commands

tail -f $CATALINA_HOME/logs/catalina.out
# check for stack traces and class not found errors

Also verify Tomcat's conf/tomcat-users.xml for the right roles and the manager URL in your plugin configuration matches the server's manager interface. Network firewalls and wrong ports are surprisingly dramatic.

Recap

You can safely build a WAR with mvn package and either let the Tomcat Maven plugin upload it or copy it into webapps like a traditionalist. Secure credentials in settings.xml fix most permission headaches. When deployment fails read the logs add any missing libraries and check context names. Now go deploy something and enjoy that brief 30 seconds of validation pleasure when the home page finally loads.