It was a few years ago, when Tomcat's version was something like 4.1.x, I do not remember exactly... My first impression was that I am swimming in a swamp, so slow it was. Whole memory on the computer was consumed by Tomcat and every click on my program interface resulted in freezing the whole machine for second and prstat (program in Solaris to supervise processes status, in Linux it is top command) indicated that CPU jumped to 100%.



After 5 years with Apache server I was completely disappointed...

I thought that those guys that always complain about Java are right: it is just waste of money, resources and time. This always hungry (in terms of resources) monster - Tomcat - will never fly!

I was not right. The problem was with settings, which were in my Tomcat's installation. Having used that Apache runs perfectly right away after an installation, I was not ready for Tomcat's performance tuning. Honestly saying I have no clue how to do that. Especially after working with httpd.conf (Apache configuration file) it was not so easy to get into multiple xml files where Tomcat's configuration is spread around. Some strange things happened here and there...

First step was to make everything working.

And after a while things began to work better and better.

First thing that I discovered was a problem with additional libraries in my web applications I used. I could not link them from Tomcat's common/lib directory. I had to have them just in one place, directly in common/lib, no linking for another place!

Second thing that I found that, even if documentation claims that "*.war files will be discovered in webapps directory and extracted automatically", they actually sometime could be there for hours and nothing happened. Sometimes it worked, sometime did not. If you make an installation package for distribution to many people, it will be safer to extract files from war files by your installation program and do not rely on Tomcat. Although you can disable this feature at all (I do not rely on it).

How to move Tomcat from one directory to another?

My answer here is for Solaris and Linux. But it is very similar procedures for Windows.

Tomcat 5.x, comparing to earlier versions, has quite good structure and properly written configuration files. There are no files with hard coded paths or versions. Everything is read from surrounding environment and it makes Tomcat very transportable. You can easily move Tomcat from one place to another. Just update environment variable $CATALINA_HOME (this variable point to "home place" of Tomcat).

For example, on my machine default place was: /usr/local/tomcat.

Later I moved it to /home/httpd/alex.

I was running Tomcat as tomcatuser and default shell for that user was "bash". To find out which shell is default in your case you need to open file /etc/passwd and locate the line with tomcat's user name. In my case the line looked like this:

tomcatuser:x:112:214:Tomcat process user/usr/local/tomcat /:/bin/bash

So, I opened the file .bashrc in home directory for tomcatuser and changed two lines:

CATALINA_HOME=/usr/local/tomcat

export CATALINA_HOME

to

CATALINA_HOME=/ home/httpd/alex

export CATALINA_HOME

That's all. Now Tomcat 5 can run from new place.

It is just a beginning about Tomcat. I continue my article about Tomcat's tuning (mostly performance) in the second part below.

Part 2

In the first part of my article I described the Tomcat installation for single user. It is good if you run Tomcat server on your very own machine. But today, when computers are so powerful, we often share an application amongst many users.

How do we install one Tomcat server to share it between many users?

After default (with default parameters offered by an installation program) installation of Tomcat for single user you get such directory structure under $CATALINA_HOME directory:

bin - contains startup and binary files

common - contains all the external libraries which are used by Tomcat (not Tomcat classes here, look for them at server directory)

common/classes

common/endorsed

common/i18n

common/lib

conf - all major configuration files are here

logs - here you find "famous" catalina.out log file and saved previous

catalina.out and more logs, like manager.log, admin.log, host-manager.log

server - here are Tomcat class files, packed in jar files and plus configuration files

for host-manager and manager. Who are them? Read later

shared - here shared classes should be

temp - place for some temp things... Do not know exactly what it is.

On my machine I see bugzilla37035-safeToDelete.tmp file with 0 bytes length here.

webapps - place where your web applications are/will be.

work - here Tomcat will place class files after the compilation. As you probably know,

Tomcat "compiles" first JSP pages into servlet java code and then compiles those servlets into

class files. That's why Tomcat named servlet container, not JSP container :-)

Now, when you got an overview on Tomcat structure, we are ready to go further.

Tomcat has the variable $CATALINA_BASE which is in case of single user is equal to $CATALINA_HOME. Just add the argument "-Dcatalina.base=$CATALINA_BASE" to startup file and $CATALINA_BASE variable must contain files for 'personal' Tomcat instance.

As you can probably assume Tomcat sharing between multiple users requires that every user have own configuration and own applications.

Usage of this argument will force Tomcat to use relative references for files in the following directories based

on the value of $CATALINA_BASE instead of $CATALINA_HOME:

conf - Server configuration files (including server.xml)

logs - Log and output files

shared - For classes and resources that must be shared across all web applications

webapps - Automatically loaded web applications

work - Temporary working directories for web applications

temp - Directory used by the JVM for temporary files (java.io.tmpdir)

Finally you get what you need to get a freedom and feel free from other guys :-)

If you do not pass the "-Dcatalina.base=$CATALINA_BASE" argument to the startup command, $CATALINA_BASE will default to the same value as $CATALINA_HOME, which means that the same directory is used for all relative path resolutions.

For troubleshooting of Tomcat server installation please look at Troubleshooting section below:

The administration and manager web applications, which are defined in the $CATALINA_BASE/conf/Catalina/localhost/admin.xml

and

$CATALINA_BASE/conf/Catalina/localhost/manager.xml files, will not run in that configuration, unless either:

- The path specified in the docBase attribute of the Context element is made

absolute, and replaced respectively by $CATALINA_HOME/server/webapps/admin

and $CATALINA_HOME/server/webapps/manager

- Both web applications are copied or moved to $CATALINA_BASE,

and the path specified in the docBase attribute of the Context

element is modified appropriately.

- Both web applications are disabled by removing

$CATALINA_BASE/conf/Catalina/localhost/admin.xml

and

$CATALINA_BASE/conf/Catalina/localhost/manager.xml

Troubleshooting section

There are only 3 things likely to go wrong during a stand-alone Tomcat installation:

(1) The most common hiccup is when another web server (or any process for that matter) has laid claim to port 8080. This is the default HTTP port that Tomcat attempts to bind to at startup. To change this, open the file:

$CATALINA_HOME/conf/server.xml

and search for '8080'. Change it to a port that isn't in use, and is greater than 1024, as ports less than or equal to 1024 require superuser access to bind under UNIX.

Restart Tomcat and you're in business. Be sure that you replace the "8080" in the URL you're using to access Tomcat. For example, if you change the port to 1977, you would request the URL http://localhost:1977/ in your browser. Remember, that all URLs (pointing to your pages, for example from one to another) that are used in application also must have a port number in every URL to work properly, including forms if they post towards your server. It is good idea to move that port to web.xml file as a parameter which is read during start up of your application. Web xml is default configuration file which is used by every application on Tomcat. You can find it under webbaps/yourapplicationpath/WEB-INF directory.

(2) An "out of environment space" error when running the batch files in Windows 95, 98, or ME operating systems.

Right-click on the STARTUP.BAT and SHUTDOWN.BAT files. Click on "Properties", then on the "Memory" tab. For the "Initial environment" field, enter in something like 4096.

After you click apply, Windows will create shortcuts which you can use to start and stop the container.

(3) The 'localhost' machine isn't found. This could happen if you're behind a proxy. If that's the case, make sure the proxy configuration for your browser knows that you shouldn't be going through the proxy to access the "localhost".

In Netscape, this is under Edit/Preferences - Advanced/Proxies, and in Internet Explorer, Tools - Internet Options - Connections - LAN Settings.

In Internet Explorer here: Tools - internet Options - Connections - LAN Settings.

In Firefox: Tools - Options - General - Connection Settings.

Everything what I described in this article is about Tomcat 5.5.15. From my experience it works well with earlier versions of 5.x Tomcat also.