dagblog.
← Archive

The Basics of Deploying Web Applications on Tomcat

Roman Pichlík ·

I’ll try to summarize the basics of deploying web applications to Tomcat. I chose Tomcat because it’s widely used, though much of this applies to other servers too. I won’t cover installing Tomcat, and I assume some basic familiarity with servlets and JSP.

Web application format (WAR)

A web application has to follow a particular directory structure so the server can handle it. This structure is called a WAR, or Web Application Archive. Let’s take a quick look.

adresář aplikace
   |  
   |--- WEB-INF
   |       |
   |       |--- classes
   |       |--- lib
   |       |
   |       web.xml
   |--- veřejné soubory (html, css, jsp, js...)

The key directory is WEB-INF. The name is always uppercase, and it’s how the server can recognize a web application. Another key part is web.xml, which holds basic configuration such as the mappings from servlets to their URLs. The classes and lib directories contain the classes and libraries the application uses. At the root of the application are files publicly accessible through the application URL, such as JSP and HTML pages.

As far as structure goes, a directory laid out this way counts as a web application that any server, or servlet container as I prefer to call it, can understand. We’ll call a directory prepared this way a WAR from here on. You can leave it as an open directory structure or package it as a ZIP archive.

A WAR thus comes in two forms:

  • An unpacked WAR, called an exploded WAR
  • A packaged WAR

A side note: the WebSphere application server won’t deploy an exploded WAR. I haven’t come across another server that can’t handle both forms.

Deploying a WAR

There are several ways to deploy a WAR.

  • Copy the WAR into the server’s deployment directory.
  • Use the server’s web deployment interface.
  • Use server-specific tools such as Ant.
  • Change the server’s deployment configuration.

Copying the WAR

In Tomcat you only have to copy the WAR into TOMCAT_HOME\webapps. Tomcat will then load it. If you package it, the archive needs the war extension, as in test.war. Unless the WAR contains a server-specific descriptor, which differs by server, the application context, part of its URL, comes from the WAR name. Whether we copy an exploded WAR called test or a packaged WAR called test.war, the context is test and the URL is http://localhost:8080/test.

Using the web interface

The web deployment interface isn’t available by default in Tomcat because none of the users has the required manager role. To grant it, edit TOMCAT_HOME\conf\tomcat-users.xml. Add the manager role to one of the users, for example tomcat, as follows: <user username="tomcat" password="tomcat" roles="tomcat,manager"/>. Then enter the URL http://localhost:8080/manager/html or follow the Tomcat manager link from Tomcat’s home page.

In the Deploy section we can deploy a packaged archive under WAR file to deploy, or an exploded archive, optionally with a context and configuration, under Deploy directory or WAR file located on server.

Using Ant

Tomcat provides a set of Ant tasks for managing the whole application. The only requirement is, once again, a user with the manager role as described above. Download the prepared Ant file and edit the following property values.

  • <property name="name" value="test" /> — the application’s context name
  • <property name="tomcat.home" value="c:\tools\tomcat-5.5.20" /> — Tomcat’s home directory
  • <property name="war.path" value="c:\temp\deployment\${name}.war" - cesta k WARu/>

Available targets

  • deploy — deploy the WAR (packaged WARs only).
  • undeploy — undeploy the WAR.
  • reload — reload the WAR.
  • list — list installed applications.
  • stop — stop the application from accepting HTTP requests.
  • start — let the application accept HTTP requests.
  • serverinfo — display information about the server.
  • sessions — display information about the application’s sessions.

Editing the server configuration scripts

Another way to deploy a WAR is to change the server’s configuration scripts. For Tomcat, create an XML file with a context definition and copy it to TOMCAT_HOME\conf\[enginename]\[hostname], usually TOMCAT_HOME\conf\Catalina\localhost\.

Here’s an example of what the file can contain.

<Context docBase="c:\temp\deployment\test.war"
    path="test"
    privileged="true" 
    antiResourceLocking="false" 
    antiJARLocking="false"  
    reloadable="true">
</Context>    
    
The docBase attribute points to the packaged or exploded WAR, using an absolute or relative path. The reloadable attribute determines whether a change in /WEB-INF/classes/ or /WEB-INF/lib reloads the application. Personally, I only got it to work for changes in lib. The path attribute specifies the application context.

Reloading an application

A common development question is how to reload an application without restarting Tomcat. There are several ways, depending on what changed.
  • Changes to public files such as JSP pages or HTML files don’t require a restart. Copy the files into the WAR and the server takes care of the rest.
  • Changing web.xml automatically reloads the entire web application.
  • Changes to classes or libraries have no effect until you reload the web application. There are several ways to do that.
  • Use the Ant file above with the reload target.
  • Call the URL http://localhost:8080/manager/reload?path=/context for the application, for example http://localhost:8080/manager/reload?path=/test (again, you need a user with the manager role).
  • For a packaged WAR, copying a new version into the server’s deployment directory reloads the whole application.
  • Use a context definition that reloads the application when WEB-INF/classes or WEB-INF/lib changes. I only got it to work for changes in lib. Define the context as follows. Create a META-INF directory in the WAR, with a context.xml file containing this element: <Context docBase="test" privileged="true" reloadable="true" /> (change the value of docBase to match your application’s context).
For small changes to classes, you can also use the JVM’s HotSwap feature. When Tomcat or any other application runs in debug mode, an agent, usually the IDE, can change loaded bytecode. That lets you modify method bodies as long as you don’t change the class definition, for example by changing an interface.
Useful links

Medium version · Archived original page

Related articles

Related CZ Podcast episodes