Deploying applications
When you view the root of your domain for the first time you will notice that a context
has been configured to serve your application. If you are not going to use Servlets/Jsp
the document root is /web, for example if you place a 'index.html' file inside this directory
this will become your home page (this is configurable - see .htaccess reference).
However, if your intent is to take advantage of Jsps and Servlets then you may wish to modify the default context
which has been deployed. Note, 'context' and 'web application' are terms which are loosely interchangeable.
The modes of deploying applications are given below.
(1) Default Context
There are three main methods of creating and/or deploying a web application, the choice you take
will depend on your development environment and/or deployment process . By default a ROOT application
will be defined when you start up Tomcat, the <Context> element in the configuration file above configures
a ROOT context so all requests for http://www.yourdomain.com/index.jsp (and other Jsps) will be
forwarded towards that context*. Similarly, requests for servlets which are mapped at the ROOT
path will be dealt with using this context (http://www.yourdomain.com/servlet/myservlet)
*Note* Tomcat treats a web application called ROOT uniquely in giving it no path, i.e. a ROOT
web application is visible at the 'root' path of the url - http://www.domain.com/
(2) Deploying using .war files
Web Application Resources (war) files are frequently used to deploy web applications. To deploy
a .war file copy the .war file into the appBase directory (see the <host> element in
the server.xml above). If Tomcat is configured to autoDeploy (again see the <host> element)
then during start up or while Tomcat is running (assuming the liveDeploy attribute within the host element
is set to "true") Tomcat will detect its presense and create a web application. The name of the war
file is used to determine the path of the deployed web application, for example if the name is
monday.war then a web application will be deployed using the path 'monday' which maps to urls under
http://www.yourdomain.com/monday/. Tomcat can be configured to 'unjar' (see host element)
the war file into the underlying uncompressed directory structure of the file, this can be
useful during incremental development when you need to make changes to the web application
while it is running.
ROOT war files
.war files with the name ROOT.war are given special treatment during deployment, when Tomcat detects
and deploys the ROOT.war file instead of creating a web application mapped to (/warname).war it
maps it to the ROOT url (http://yourdomain.com/). However, because the ROOT context is preconfigured
within the server.xml above deploying a ROOT.war file will have no affect because a ROOT context
already exists. To deploy ROOT.war files, stop Tomcat, remove the ROOT <context> and restart
Tomcat.
(3)Deploying using directories
Tomcat is intelligent to understand that directories which resemble the structure of a web application
that exist beneath the appBase directory are suitable candidates for deployment. If a directory
contains a WEB-INF directory then Tomcat will attempt to deploy it. In reference to the special treatment
of the symbolic ROOT creating a ROOT directory beneath the appBase will have the same affect as
1 or 2 (with a ROOT.war file).
(4)Deploying .xml files
The final method of deploying web applications is using .xml files within the appBase directory (now deprecated).
Later versions of Tomcat also look with a special directory within its configuration directory for xml files to deploy:
$TOMCAT_HOME/conf/Catalina/www.domain.com/
When Tomcat is running (assuming autoDeploy is set to true) or when started up it scans these directories
for files with .xml extensions. The content(s) of this file(s) should have contain a 'context' element
xml structure identical to what is expected within the server.xml. If the contents adhere to this
specification (DTD) then Tomcat will deploy the application. The benefits of this approach
over the above are you can specify Tomcat specific configuration options such as JNDI resources. However,
there is no real difference between this option and editing the server.xml configuration file apart from
being able to deploy xml files at runtime rather than start time.
Connection Pooling
A popular configuration option is to take advantage of connection pooling within Tomcat. In accordance to the
Servlet 2.4/JSP 2.0 specification Tomcat provides a JNDI (Java Naming Directory Inteface) Context for each application, this allows an application to 'lookup' values and resources which have been configured within the server.xml and/or the web.xml file. This is how the connection pooling works, the steps taken to configure and use it are:
- Define the resource inside the server.xml
- Declare the resource inside the application's web.xml
- Lookup the DataSource object
The definition of the DataSource is contained in the server.xml above commented out, to define it
uncomment it and replace the url, driverClassName, username, password element values with values applicable to you.
The next step is to declare the resource within the web.xml file, ensure that when you enter the resource-ref
element (and the element's within it) into the web.xml file it appears in the correct order to the other elements in compliance with the web.xml
DTD.
<resource-ref>
<description>DB Connection</description>
<res-ref-name>jdbc/dbconnection</res-ref-name>
<res-type>javax.sql.DataSource</res-type>
<res-auth>Container</res-auth>
</resource-ref>
When the steps above have been completed restart Tomcat so the changes inside the server.xml will be applied. To
use the connection pool a InitialContext must be found. The simple class below demonstrates how to
obtain a javax.sql.DataSource and a java.sql.Connection object:
import java.sql.Connection;
import javax.sql.DataSource;
import javax.naming.InitialContext;
import javax.naming.Context;
import org.apache.log4j.Logger;
/**
* Very simple ConnectionPool wrapper
*
* @author James Williamson
* @version 0.01
*/
public class ConnectionPool
{
/** Our Logger object */
private static Logger logger =
Logger.getLogger(ConnectionPool.class);
public static Connection getConnection() {
try {
Context ctx = new InitialContext();
if(ctx == null)
logger.fatal("Cannot get initial Context");
DataSource ds =
(DataSource)ctx.lookup("java:comp/env/jdbc/dbconnection");
return ds.getConnection();
} catch (Exception e) {
logger.fatal("Cannot get connection",e);
return null;
}
}
}
Tomcat Admin Application
The Tomcat admin application provides a web front end for configuring Tomcat, with the
added bonus of it being able to commit your changes to the underlying server.xml file.
As this is fundamentally a standard web application the process for installing it remain
near synonymous with that of any other web application. However, there are two crucial aspects which
differ and must be configured for it to function. The first is the admin application is
'privileged', that is it can access the ClassLoader
used by the server side of Tomcat thus giving it the ability to modify the internal Tomcat configuration
in realtime whereas a restart would normally be required.
The second: it requires the use of Realms to ensure the administrator has authenticated
themself before gaining entry.
A typical entry to configure the admin application is shown below, note that privileged attribute has
been set to true and the evidence of a Realm used for authentication. The choice of Realm is
configurable, in this instance the MemoryRealm is used (although database, LDAP and others are available).
Because the path isn't specified as an attribute, Tomcat will by default look inside
/usr/tomcat/conf/tomcat-users.xml for details of authentication information.
Section of server.xml used to configure Host and assoicated admin app
<Host name="hostname">
<Logger className="org.apache.catalina.logger.FileLogger"
prefix="hostname." suffix=".log" directory="/home/username/logs"
timestamp="true"/>
<Realm className="org.apache.catalina.realm.MemoryRealm" />
<-- The ROOT context -->
<Context path="" appBase="/web" />
<-- The admin context, this will be visible at http://www.hostname.com/admin -->
<Context path="/admin" appBase="/web/admin" privileged="true" />
</Host>>
Contents of the tomcat-users.xml file
<tomcat-users>
<user name="tomcat" password="tomcat" roles="admin" />
</tomcat-users>
The roles attribute within the tomcat-users.xml file should map to the
entry within the web.xml of the admin web app which declares the security
role required to gain access to the application. By default the admin
is set to 'admin' so the only change required is to modify the tomcat-users.xml
file setting the desired username/password. Before restarting Tomcat ensure the admin
directory exists in the path specified within the server.xml file.
Once these changes are complete restart tomcat and
redirect you browser to http://www.youdomain.com/admin/, you should be presented with an
admin screen. Login using the username,password you suppliled within the tomcat-users.xml
file. An important element of the admin app is it allows you to commit the changes you have
made while using this app permanently, the 'commit changes' writes out the running config back to the server.xml.
Running Tomcat headless
If you are seeing stack traces with classes belonging to java.awt in them
and are using image manipulation libraries that it is most likely you need to
run Tomcat 'headless'. Adding this line into the top of the catalina.sh will instruct the JRE to
start running within a 'headless' environment:
JAVA_OPTS-Djava.awt.headless=true
If errors occur the problem will often be related to the parameters given in the
server.xml. Check the logs for stack traces indicating where the error occurred. If you
require assistance email support@nameonthe.net.
Version: 1.1
Date: 15/05/2005
