Skip directly to searchSkip directly to the site navigationSkip directly to the page's main content

View System Documentation - Tomcat Notes

This document contains notes and some items to consider if using Tomcat as the Java web application server. Of course the IBIS-PH View System should be deployable to any Java web application server but this page only deals with Tomcat as this is one of the main reference platforms. Also, this page does not contain step by step instructions on how to install a Java JDK or JRE or the Tomcat application server on a Windows or Linux box. There are plenty of these tutorials/instructions available on the web and in books. As already stated, this page contains the specific items changed and any notes on topics that pertain to how the Java JVM and Tomcat were setup/what needs to be configured. Throughout this document it is assumed that the application server (Tomcat) is a dedicated set for the IBIS-PH applications although other applications could be hosted. The next section serves as an index and also provides a simple outline of the general steps needed to get Tomcat configured so that the IBIS-PH View System can be deployed.

Installation Steps

  1. Download and install J2SE JDK 1.6+ from Sun's site. As of 1/2005, IBIS-PH doesn't use any of the new features of Java Version 1.5 but the class files are compiled using JDK 1.6. Plus 1.5+ has seen some speed and XML improvements that are worthwhile. Tomcat 5.x requires Java JVM 1.5+, while Tomcat 4.x can use either JVM (any 1.2+ JVM). If the platform is Windows it is recommended to download the Windows version that has the installer which sets the appropriate paths etc. Make sure that the JDK is downloaded NOT the JRE! If using previous version the source Java code will need to be complied for the destination JDK.
  2. Download the Tomcat app server package from the Apache Tomcat site. Follow links to the downloads and select the desired version. Again if the target platform is a Windows operating system and it is desired to have the application server run as a Windows service then download the Windows installer version.
  3. Install Tomcat
  4. Setup/configure the Tomcat Java JVM
  5. Edit/configure Tomcat's default web application behaviour (web.xml)
  6. Edit/configure Tomcat's control file (server.xml)
  7. Physically delete/remove the standard Tomcat webapp(s)
  8. Deploy the IBIS-PH View System webapp

Misc Info



Tomcat Install Overview

Tomcat comes in either zip, tar, rpm, or Windows exe format for the specified OS and CPU. Basically what happens is that the Tomcat system files are extracted into a directory. The main thing that the system needs is to have the Java environment setup and some environment variables that should be set, which are:

Windows installer note: If installers used then only the CATALINA_OPTS probably needs to be set as everything else is handled by the program's setup.

See the Tomcat Jarkarta website for more information on setup.

Multiple Tomcats Note: If on the same box, then modify the startup (.sh/.bat) catalina files and specify the appropriate JAVA_HOME and CATALINA_HOME variables in those files. There are other ways to make this work as well - that's simply one. Listed below are the changes made to the startup.bat and catalina.bat file.
startup.bat:
REM Commented out the usage of the existing Tomcat4 env variable:
REM if not "%CATALINA_HOME%" == "" goto gotHome

catalina.bat (added to the top and switch back at the bottom):
set TEMP_JAVA_HOME=%JAVA_HOME%
set TEMP_CATALINA_HOME=%CATALINA_HOME%
set JAVA_HOME=d:\java\1.5.1
set CATALINA_HOME=d:\tomcat5


For Linux, modified the catalina.sh file to have this at the top:

JAVA_HOME=/usr/local/java/jdk1.5.0_02
JAVA_OPTS="-Djava.awt.headless=true"
CATALINA_HOME=/usr/local/jakarta-tomcat-5.5.9
CATALINA_OPTS="$CATALINA_OPTS -server -Xms1024m -Xmx1024m -Xmn256m"

Headless graphics

Batik requires Graphics2D, the standard Java API for 2D graphics, to generate the images. This may be a problem with UNIX or Linux Web servers because Graphics2D needs an X11 server, which seldom runs on Web servers. Since JDK 1.4, you can run a so-called headless application by setting the java.awt.headless property to true. Note that the JDK still links to the X11 library, but the server doesn't need to be started. You can set the property directly on the command line or environment variable like above:

java -Djava.awt.headless=true


Setup Tomcat Account

This runs Tomcat as something other than root/system. Doing this simply locks down the possibility of a stray application getting on the system and being able to do damage. This is outlined in the Wrox Apache Tomcat 5 book and is also discussed in numerous websites like jGuru. Listed below are some general steps from the book:

Windows:


Linux:


For more specifics on file privs etc. see: Chapter 15, Tomcat Security, of Professional Apache Tomcat 5. ISBN: 0-7645-5902-8

Windows Tomcat Setup

Run the .exe file which runs a windows setup. This steps you through everything and installs a tomcat service which can auto start on system startup.

Windows Service Notes: If you want the system out log, you'll need to check the Tomcat service's "allow to interact with the system" checkbox.

IMPORTANT: For Windows XP, Server 2003, and after, the "mssvcr71.dll" either needs to be copied into the "windows/system32" directory or the "c:/java/jdk1.6/bin" (or whereever the JVM is installed) needs to be part of the system's path so that the dll can be found and loaded. If this is not done the Apache-Tomcat service will not be able to start. Later versions of the Tomcat installer must have fixed this issue since it appears to not be an issue for Adopters in 2008.

If this step is done by hand, simply unzip the installation package and set the environment variables. You can then run the [CATALINA_HOME]/bin/startup.bat to start, and press [Ctrl]-c in the system out window to stop the server or run the shutdown.bat file located in the same bin directory. The startup.bat then needs to be part of the one of the Windows on startup mechanisms.

Linux Tomcat Setup

IMPORTANT: For the Batik Graphics to be able to convert SVG to JPEG on Unix, the headless environment variable or Java system property must be set.
Env Var: JAVA_OPTS='-Djava.awt.headless=true'
JVM 1.4+ System Property: java.awt.headless=true
See Paul Leo's system setup document for the main meat.



Multiple Tomcat Installs on the Same Server

Here's a simple list for multiple installs on the same server. Of course there are many options here including one install with multiple engines etc.

JVM Memory Settings

Add the JVM memory settings within the env var CATALINA_OPTS (JAVA_OPTS also works but will apply the settings to any JVM request). There isn't a hard and fast rule on what these numbers should be because it depends on a variety of factors. The Apache Tomcat5 book recommends setting the Xms and Xmx the same to minimize the time it takes to grow the heap. It is recommended to specify a considerably lower value than the amount of physical RAM in your system, so the operating system and other applications will also have enough space. Otherwise the swap memory of the operating system will be used, which can result in high disk activity (thrashing), and reduced system performance. See Bea's JVM Tuning Page for info on how to tune WebLogic and general JVM settings.

NOTE: This settings are for Sun's JVM. Other JVMs may have different command line settings. Also, these settings might not apply to latter versions of the JVM.

Basically there are 3 main values that should be set. These are the min heap size "Xms" the max heap size "Xmx" and the server flag "server".

Example:
LINUX: CATALINA_OPTS="$CATALINA_OPTS -server -Xms256m -Xmx512m"
WINDOWS: set CATALINA_OPTS=-server -Xms256m -Xmx512m

NOTE: Server mode instructs the JVM to perform more extensive run-time optimization. This flag MUST be the first argument/parameter specified otherwise it will be set as a "client" (according to http://java.sun.com/docs/hotspot/PerformanceFAQ.html). Specifying the "server" flag means that right after startup the system will have slightly slower execution, but after the JVM had enough time to optimize the code, the execution should be faster.


Garbage Collection

Again this may or may not apply to the later JVM versions. These notes are simply here for historical purposes and may prove to be useful.

It appears that when specifying garbage collection that if large amounts of memory (greater than 256M) are specified then the incremental compacting GC should not be used for performance reasons (-Xincgc). This bottleneck was experienced when running Tomcat4 with Java 1.4 on Susue Linux 9, and heap of 512m to 1024m. According to Sun on JVM 1.3, if you need lots of memory and experience a GC delay, try setting the "eden" sizes: -XX:NewSize=128m -XX:MaxNewSize=128m (or set a ratio of old to new via -XX:NewRatio=8). Another way to set this size is using -Xmn256m. Eden is where all new objects are created. According to Sun, most objects are short term objects and as such are better off caught in a small memory area that is quickly and easily garbage collected (e.g. don't have to go through a huge memory pool). The long term objects are then copied into the perm heap area and GC'd differently. Also, turn on GC messages by issuing this on the command line: -verbose:gc -Xloggc. Can also profile heap usage by -Xrunhprof:heap=all or other option, try -Xrunhprof:help. Also see jvmstat tool. Also note that these settings are for Sun JVMs 1.4+.

JVM 1.5:
This might be something to try also: Use the parallel young generation collector (-XX:+UseParallelGC) along with the adaptive size policy feature (-XX:+UseAdaptiveSizePolicy).

JVM Links


NOTES:
Tried CATALINA_OPTS of: -server -Xms256m -Xmx256m -heapsize32m -freememory20m but these heap and free mem settings wouldn't work as documented.

ANOTHER OPTION - EDIT CATALINA.SH (linux) or CATALINA.BAT (windows)

Can also set the JVM memory settings by modifying this script file which is typically used to start Tomcat. These files can also be modified for the HOME enviro vars so that the environment variables are not needed/used. Both of these files are located in the [CATALINA_HOME]/bin directory.

WINDOWS SERVICE: If Tomcat was installed on Windows as a service then the enviro variable probably doesn't need to be set depending on the version and the installer (test). Or, if installed you should be able to set by going to: Start / Programs / Apache / Tomcat 5.0 / Configure Tomcat. This will open up a dialog box to change settings. Click the middle tab, Java VM. There is a text area to add Java Options. After the last entry/value, add -Xms###m -Xmx###m. Click Apply or OK, and restart the Tomcat service.

NOTE: This requires Tomcat to be started and the system apps to not be removed as outlined/semi-recommended in this document.

EXAMPLE JVM SETTINGS FROM COCOON V2:
(default)64128256384
Xms0000
Xmx 64100228356
heapsize 6080208236
freememory 1202020


So if you see errors like:
java.lang.OutOfMemoryError <<no stack trace available>>
java.lang.OutOfMemoryError <<no stack trace available>>
Exception in thread "main"
Then you'll need to increase the stack space.


Edit Tomcat's Default Webapp Behaviour

The file $CATALINA_HOME/conf/web.xml is the default system Deployment Descriptor for all web applications. Each IBIS-PH application specifies most of these settings but it's still a good idea to have a default welcome page and general error pages even though the IBIS-PH apps specify these.

IMPORTANT: Make a backup copy of this file before editing. Also note that the elements are ordered and that these elements MUST be in an exact order. See Bea's web.xml defs for more info on each element.


ENABLE / DISABLE DIRECTORY LISTINGS AND MAKE HTTP READ ONLY

Edit the $CATALINA_HOME/conf/web.xml file and locate the main servlet element's init params (located in the upper section). Change the parameter's value with the 'param-name' of 'listings' from 'true' to 'false'. Tomcat defaults with the system being in read only mode but it's best to make sure explicitly. Add a 'init-param' element like given below. "Read-Only" means that HTTP DELETE and PUT requests are rejected. 
<servlet>
	<servlet-name>default</servlet-name>
	<servlet-class>org.apache.catalina.
		servlets.DefaultServlet</servlet-class>
	. . .
<init-param> 
	<param-name>listings</param-name>
	<param-value>false</param-value>
</init-param>
<init-param> 
	<param-name>readonly</param-name>
	<param-value>true</param-value>
</init-param>
. . .

REMOVE / COMMENT OUT INVOKER SERVLET

Comment out or delete the servlet invoker definition and mapping: 
<servlet>
	<servlet-name>invoker</servlet-name>
. . .
		and 
<servlet-mapping>
	<servlet-name>jsp</servlet-name>
	<url-pattern>*.jsp</url-pattern>
</servlet-mapping>

SET DEFAULT SYSTEM WELCOME PAGES

The welcome pages are simply a list of files/urls that will be called if a general, non specific application request is made to the system. If it is a general request to an application e.g. http://ibis.health.utah.gov/ibisph-view then the "ibisph-view" application will have a welcome list that will be used (as well as a default servlet call). If an application is installed as the "ROOT" application or has it's application path set to "/" then it's welcome pages will be used first for the system. Else, the files listed here will be used in the order they are listed (e.g. if it can't find the first welcome file it will go to the next one). Also, note that the items listed MUST be a file and NOT an application servlet call.

BOTTOM LINE: This isn't needed because the IBIS-PH applications provides this. However, below is a sample of what this would look like if it was needed. 
<welcome-file-list>
	<welcome-file>index.html</welcome-file>
	<welcome-file>/ibisph-view/index.html</welcome-file>
<welcome-file-list>

SET ERROR PAGE

At a very minimum, the HTTP 404 code should be handled in case a request is made to the general system that does not exist (same bottom line as the welcome pages). 
<error-page>
	<error-code>404</error-code>
	</location>http://health.utah.gov/error</location>
<error-page>

SETTING DEFAULT SESSION TIMEOUT

This value really isn't needed for IBIS-PH apps since each already specifies this value in their respective web.xml files. In any case if a default is wanted for the system set this value: 
<session-config>
	<session-timeout>30</session-timeout>
</session-config>
"default" SERVLET NOTE: This is required for the system to function. Also, if any of the applications need to serve files then the url pattern of "/" is needed. Without this pattern there is no process to locate and stream back data files. If not specified then each app needs to have a file serving servlet...



Edit / Configure Tomcat's server.xml

This is the main configuration file that controls the host engine and application contexts. These are optional and is not needed for the application to work but are some common entries that some system administrators should consider changing.

IMPORTANT: Make a backup copy of this file before editing.

See Demystifying Tomcat 4's server.xml File for more info on each element. Or Tomcat's docs.

CHANGE SHUTDOWN PORT AND SIGNATURE

<Server port="8007" shutdown="remoteshutdown" debug="0">

CHANGE CONNECTOR'S PORT AND ENABLE COMPRESSION

Leave at 8080 for OIT. I change it to 80 so I don't have to do localhost:8080 in my development environment. Also, for faster development, leave the compression off. Some sites might want to use 80 if on Linux there's a way to keep on 8080 and remap 80 to it (see Paul Leo's setup document). 
<Connector port="80"
	maxThreads="150" minSpareThreads="25" maxSpareThreads="75"
	enableLookups="false" redirectPort="8443" acceptCount="100"
	connectionTimeout="20000" disableUploadTimeout="true" 

	*** BELOW IS FOR TOMCAT 5 ONLY AND ONLY FOR PRODUCTION ***
	compression="on"  compressionMinSize="2048" 
	noCompressionUserAgents="gozilla, traviata" 
	compressableMimeType="text/html,text/xml"
>

CONFIGURE ACCESS LOGS TO BE READABLE FOR TRENDING PACKAGES

If this app server is being front ended by Apache, performance can be increased by not logging access. If this is the case, then skip this. Else, within the Engine element set a value element to be like the one below (pattern attribute is the key): 
<Valve className="org.apache.catalina.valves.AccessLogValve" 
	directory="logs"
	prefix="access"
	suffix=".log"
	resolveHosts="true"
	pattern="common"
/>
And, define the actual logger class. Within the Host element make sure there's an entry like: 
<Logger className="org.apache.catalina.logger.FileLogger" 
	directory="logs" 
	prefix="localhost_log." 
	suffix=".txt" 
	timestamp="true"
/>
See http://www.faqchest.com/prgm/tomcat-l/ tmct-02/tmct-0210/tmct-021056/tmct02101513_20837.html for more specifics.

TURN OFF UNPACK and AUTO DEPLOY

For speed, and security, remove the autodeploy and unpacking of wars from a production environment. For development, leave these on and also set the 'appBase' set to the CVS/ IBIS folder's webapps directory. This allows for everything to be kept in one directory for easy backups and easier management of all the related project work products. Note that you can leave the WAR packed for even tighter security. This doesn't allow for hot patching of files and according to the docs will be a little slower than when compared with a fully extracted war. If using a process where a Maven or Ant build is pushed to the app server then the auto deploy should be enabled otherwise the app server will have to be restarted. 
<Host name="localhost" debug="0" appBase="webapps" 
	unpackWARs="false" autoDeploy="false">

REMOVE ALL OTHER WEBAPP CONTEXTS

For a production environment, comment out or remove all the defined "Context" elements which includes examples, ROOT, etc. These elements are contained within the Host element and look like: 
<Context path="/examples" docBase="examples" debug="0"
	. . .

ADD IBISPH VIEW SYSTEM CONTEXT

There are several ways to set the View system as the default app. Rename the app's main directory as "ROOT", specify in the context in the app's META-INF/context.xml file or set the context in the server.xml file as shown below: 
<Context path="" docBase="ibisph-view" debug="0" 
	reloadable="false" crossContext="false"
/>
<Context path="/ibisph-view" docBase="" debug="0" 
	reloadable="false" crossContext="false"
/>
NOTES: For development, leave the reloadable="true" so that the app will auto reload whenever any of the class files change (e.g. if re-compiled). For those that do NOT want cookie support, add the cookies="false" attribute to the Context element. Session objects will then use URL re-writing.

TWO CONTEXTS FOR A GIVEN APP: Tomcat requires a default/root app. Tomcat also auto creates contexts within applications it finds within it's default appBase folder. So if the view system is setup as the default app, Tomcat will auto create a context with the path of "/ibisph-view/". The problem/issue is if there are 2 contexts both pointing to the same docbase then you'll get 2 instances of the same app within the webapp server container/JVM which run separately but use/share the same files. So for something like artifacting, you'll have files which have navigation built for potentially two different contexts. In the old way of artifacting a hash was used which really could get things messed up pretty quick - concerning. To get around this create a blank or a dummy docBase which matches the /ibisph-view path. This forces Tomcat to not auto create a working "ibisph-view" app. Note that Tomcat 559 will complain if a base of "dummy" or any other invalid/non existent directory name is specified. It doesn't complain about "" being used. There are other ways around this also like not having a "base" webapps directory and simply having a single app under a single virtual host. Also can put directory outside of the base directory then the path looks funny etc.

ANOTHER WAY NOTES: Specify the Host appBase attribute to be: webapps/ibisph-view then set the docBase of the context to / and the admin's docBase to ../ibisph-admin. The blank dummy context can then be removed. The view system as of Oct, 2005 handles both contexts being used. However, with artifacting, the first time the page is artifacted is how the menuing system will be saved. So if the ibisph-view/home/Welcome.html is hit first then all of it's navigation will be ibisph-view/... (which works) but then if someone else comes and hits a page as the root/default app then some pages will have the ibish-view context while others will have navigation links that have a blank context.

WARS, AUTODEPLOY, CONTEXTS: if a context is specified, the war won't auto redeploy (even if enabled). To get around this you need to delete the app's files and then the system will auto deploy the war (assuming enabled and the war is in the webapps directory).

DEVELOPMENT DIRECTORY NOTE: If you have your webapp located outside the normal directory specified with the Host element then you'll need to explicitly point to that directory in the "docBase" attribute.



NOTE ABOUT APP SERVLET MAPPING (web.xml): You can have a blank servlet alias but then everything will be funneled through that servlet. So all requests for jsps javascripts, css, etc. would all hit that servlet and not be served up as web content.

HTTPS Configuration (Optional)

HTTPS allows data sent to/from the server to be encrypted using Secure Socket Layer (SSL). This secure data communication is desirable when dealing with sensitive query datasets or sensitive indicator profiles etc. Note that to be effective, an authentication and authorization mechanism needs to be utilized in addition to the encrypting of the data transferred. Also note that a separate installation of the application should also be considered to ensure that all requests and traffic are authorized and encrypted.

The basic steps are:
  1. If you are running a 1.3 JVM (version 1.4+ already has this bundled in), download JSSE 1.0.3 (or later) from http://java.sun.com/products/jsse/ and either make it an installed extension on the system, or else set an environment variable JSSE_HOME that points at the directory into which you installed JSSE.
  2. Create a certificate keystore by executing the following command:
    Windows: %JAVA_HOME%\bin\keytool -genkey -alias tomcat -keyalg RSA
    Unix: $JAVA_HOME/bin/keytool -genkey -alias tomcat -keyalg RSA
    and specify a password value of "changeit".
  3. Uncomment the "SSL HTTP/1.1 Connector" entry in $CATALINA_HOME/conf/server.xml and tweak as necessary.

See the Tomcat SSL how to/setup documentation for more detailed instructions.

Character Encoding (Optional)

Tomcat again uses iso-8859-1 per default to decode those GET parameters regardless of which encoding is set in the request even if it is set by an apps filter. To change this behavior you have to change connector configuration inside the server.xml of your Tomcat as described here. The attribute URIEncoding defines a fixed encoding the server uses for every request. What we want to use is the attribute useBodyEncodingForURI which tells the server to use the encoding defined for the body for the GET parameters too.


Delete / Remove Default Tomcat Installed Webapps

Physically delete/remove the standard Tomcat webapp(s) which were auto installed. Even if the app's context is removed from/doesn't exist in the server.xml the app will still load/be available (the Host's autodeploy attribute doesn't control this either - it's only a default for war files placed in the root of the webapps directory). These apps are located in the [CATALINA_HOME]/webapps directory (or where ever specified in the server.xml file) and can include:
If the manager and/or admin apps are to be kept then see how to secure Admin and Manager in Chapter 15 of the Apache Tomcat book already mentioned on this page. Otherwise these should also be removed from the [CATALINA_HOME]/server/webapps directory. These apps are in a directory named:


IBIS-Q CGI Tomcat Setup/Configuration

After many hours of searching/reading/trials and errors here's the only way I could get this work on Tomcat5.




Test URLS

Note: favorite bookmarks are stored in the user's area under my favorites (for IE) and typically in C:\Documents and Settings\username\Application Data\Mozilla\Firefox\Profiles\default.7pi\bookmarks.html for NS/FF.

LOCAL / DEVELOPMENT MACHINE:
General Tomcat
Local View System (assuming the app is the default app, if not add the appropriate app context path)

BATIK 1.5 & 1.6 - JARs

TO WORK ON LINUX: export JAVA_OPTS='-Djava.awt.headless=true' need Java 1.4.1+ for this to work.

JARS NEEDED (for transcoding):
NOT NEEDED:

Security

JAAS Security == to Spring/ACEGI


Linux Symbolic Links

There are several ways to locate the webapps to another spot rather than the default [CATALINA_HOME]/webapps dir. They include setting the value in the server.xml file, standard Linux symbolic links, and the context configuration as outlined below: 
<Context path="/myApp" docBase="myApp" debug="0">
  <Resources 
	className="org.apache.naming.resources.FileDirContext" 
	allowLinking="true"
  />
</Context>
With the default catalina.policy, this still won't work if your jar is outside of the web-app, and you are running "-security". In this case you also need to edit catalina.policy to grant rights to the file.


URLS / Links