Multi-Instance Deployment from Eclipse to Tomcat

Problem

• You are developing a web application for Tomcat in Eclipse.
• You want to deploy multiple instances of the same application with different configurations directly from your workspace.
• Of course, you don't want to duplicate any projects in your workspace.

Solution

This scenario can be solved quite easily with the vanilla Apache Tomcat adapter of Eclipse WTP. There is no need for any additional Eclipse plugins.

Background on Eclipse WTP

Eclipse Web Tools Platform (WTP) is an Eclipse subproject providing plugins for web application delevelopment. It is bundled with with Eclipse IDE for Java EE Developers and can be installed on top of other editions.

Using Eclipse WTP, you can run and debug your project in a servlet container directly from your Eclipse workspace. Apache Tomcat is supported by WTP out of the box. For other servlet containers or full-blown application servers like GlassFish or JBoss, you need to install a server adapter plugin.

If your project is built with Maven, you should also install m2e und m2e-wtp.

Configuring a Tomcat Server for Eclipse

All Eclipse WTP server adapters require a stand-alone server installation, outside of Eclipse, e.g. /opt/apache-tomcat-6.0.32.

In Eclipse, create a Tomcat Server via Preferences | Server | Runtime Environment | Add... | Apache Tomcat v6.0, click Next and enter your Tomcat installation directory.

Opening the Servers view, you'll now see a Tomcat v6.0 Server at localhost. Double-click on this entry to open a form editor with additional settings.

The Server Locations section has three different options. If none of them is activated, go to the Servers view, delete all modules on the server and select Publish from the context menu.

These options define the location for web applications and Tomcat configuration files published by Eclipse WTP:

1. a directory in the Eclipse workspace (something like .metadata/.plugins/org.eclipse.wst.server.core/tmp0)
2. directly in your local Tomcat installation
3. any other directory outside of Tomcat or Eclipse

Using option 3, you are completely independent of your Tomcat installation, whereas option 2 comes with a risk of modifying some installation configuration, which comes with option 2.

Under Server Options, make sure to check Publish module contexts to separate XML files. With this setting, Eclipse WTP stores each web application configuration in a separate file under conf/Catalina/localhost.

Configuring your web applications

In Tomcat, a web application is usually configured by a context.xml configuration file located in ${catalina.base/conf/Catalina/localhost. A web resource META-INF/context.xml inside the web application has the same effect. For a Maven project, make sure to place this file in src/main/webapp/META-INF and not in src/main/resources/META-INF.

Multiple instances of a web application

Using Eclipse WTP, you can run multiple instances of the same web application on Tomcat directly from the workspace. Any changes to Java sources or web resources in the workspace are directly published to all running instances.

For example, let's take a web project myweb which we'd like to run in its default configuration and in an alternative configuration as myweb2. We assume the server location to be /opt/wtp (see option 3 above).

Now we simply copy the modified context.xml for myweb2 to /opt/wtp/conf/Catalina/localhost/myweb2.xml and let the docBase attribute in this configuration point to the same directory as for myweb:

<Context docBase="/opt/wtp/wtpwebapps/myweb" reloadable="true">
    ...
</Context>

If we now start the project myweb via the context menu Run As | Run on Server, Eclipse WTP will launch two instances of our web app under the following URLs

http://localhost:8080/myweb/
http://localhost:8080/myweb2/

The context path of a web application is the project name by default. If you want to change myweb to myweb1, you can set the context root under Project Properties | Web Project Settings. For a Maven project under m2e-wtp, set the property m2eclipse.wtp.contextRoot in your POM.

The same approach can be used to launch non-workspace applications together with your workspace application in the same Tomcat instance. Simply copy the WAR to /opt/wtp/webapps/foo.war and the context file to /opt/wtp/conf/Catalina/localhost/foo.xml.

See also

WTP Tomcat FAQ
m2e-wtp FAQ