I used to use the sysdeo Tomcat plugin in Eclipse for my development, but someone suggested that I take a look at the Eclipse Web Tools project, which is an application server feature for Eclipse. It seems like it is the mechanism through which Eclipse is planning to support application servers in the future, so I thought it would be worth a look.

However, once I got it installed, I ran into a problem that is mentioned a few times on various sites on the web, but with few solutions. When I tried to run the application server, I got the following message:

Due to new licensing guidelines mandated by the Apache Software Foundation Board of Directors, a JMX implementation can no longer be distributed with the Apache Tomcat binaries. As a result, you must download a JMX 1.2 implementation (such as the Sun Reference Implementation) and copy the JAR containing the API and implementation of the JMX specification to: ${catalina.home}/bin/jmx.jar


This article describes the workaround that I discovered to make Tomcat 5.0 work correctly inside Eclipse.

But first, let’s step back to find out how I arrived at my current state.

From the Eclipse Web Tools home page, they have a link on the top-right hand side that takes you to the latest download page. For me, I used Version 1.5.2 of the WTP.

On that page they conveniently provide a link where you could download, in one thumping big file, a single zip that contains Eclipse 3.2.1, WTP 1.5.2 and all the other pre-requisites (beware, it is about 200MB!)

On my Ubuntu machine, I originally installed eclipse using apt-get, which installs into /usr/share/eclipse. To preserve all my existing shortcuts, I just renamed that directory to be /usr/share/eclipse3.1, and unzipped the new eclipse into /usr/share/eclipse. I am not really sure if that is the sanctioned way (probably not), but it worked perfectly for me.

Before you create a new project, you will need to go into the Windows/Preferences menu item, and open the Server settings dialog. In here, add a new Server Runtime for Tomcat 5.0 and point it to your default tomcat directory (/usr/share /tomcat5 for me).

From there it was a simple matter of creating a new Dynamic Web Project, where it asks me which “Target Runtime” I wanted to deploy into, and I chose the newly created Tomcat 5.0 runtime.

I then developed a simple web application, and when I attempted to start the Tomcat instance, I got the above error message. Searching on the web didn’t give me too much love, and interestingly, I don’t get this message when I start Tomcat using /etc/init.d/tomcat.

Anyway, the solution I found was to edit the runtime classpath of the application server (from the Run/Run… menu) to include the following entries:

Once I applied those changes, and restarted my application server, everything was working like a champion.

One of the challenges on the web at the moment is that many sites want you to register a “free” userid just to do the most mundane thing (such as downloading a file, viewing a picture, etc). While I don’t have a problem with that requirement in general, I am often quite sceptical about what they plan to do with my userid.

There is a common technique that many people use where they create a site-specific version of their email address (I believed it is often called “plussed email addressing”). For example, let’s say that my actual address is edwardaux@mydomain.com and I wanted to signup to flickr, I could
create an email address called edwardaux-flickr@mydomain.com and use that (and tell my mail server to forward all email to that address to my real edwardaux@mydomain.com address). The nice thing about this is that if flickr is naughty (not that I am suggesting they are) and sells/gives my email address to spammers, I can immediately determine that by looking at who the email was addressed to.

The problem with this approach is that I have to go into my mail server ahead of time and manually create each site-specific email address. That is a bit of a hassle, and I am sure that I can get away with a simpler approach.

So, given that I am using a combination of qmail and vpopmal to manage my mail server, how might I configure them to do what I want?

Looking at the qmail documentation, I see that the suggested mechanism is to manipulate a file called /home/edwardaux/.qmail-xxx, where xxx is the site-specific alias I want. For example, .qmail-flickr would match any email coming to edwardaux-flickr@mydomain.com. However, this still means that I have to manually create explicit files for every site I want to sign up to. There is another special variant of this file called .qmail-default, which is the catch-all for all addresses that don’t have a specific .qmail-xxx that matches the incoming mail. It looks like this is the guy I want because it should mean I don’t have to keep creating explicit files.

However, as I am using vpopmail to manage multiple domains, the default .qmail-default file location will not work because qmail doesn’t deliver the mail directly to my /home/edwardaux mailbox. Instead, it hands all mail to vpopmail who then decides which virtual domain and virtual user to deliver it to. So, looking at the vpopmail configuration files, I found one called /home/vpopmail/domains/mydomain.com/.qmail-default. This is the catch-all configuration file for all mail delivered to the mydomain.com virtual domain.

vpopmail supports a subtle variation on this file that incorporates the user’s email address. I created a file called: /home/vpopmail/domains/mydomain.com/.qmail-edwardaux-default and added the following:

| /home/vpopmail/bin/vdelivermail ” edwardaux@mydomain.com

Note that the above line contains two single quotes (‘), not a double-quote (“)

What this does is forward all mail that is addressed to edwardaux-anything@mydomain.com to edwardaux@mydomain.com. A quick restart of qmail (/var/qmail/bin/qmailctl restart) and I was set to go. So, now I can dynamically make up as many combinations of edwardaux-xxx@mydomain.com as I like without having to create individual .qmail-xxx files ahead of time.

One thing that you need to be conscious of, though, is that now if spammers send mail to edwardaux-aaa@mydomain.com, edwardaux-bbb@mydomain.com, edwardaux-ccc@mydomain.com, then all that will come through to my inbox, whereas it used to just get thrown away. I think I can live with that, though.

Enjoy!

This describes the process for configuring Tomcat 5 on Ubuntu (or Debian) so that you can have multiple instances of Tomcat running. Typically, this would be useful when you have several domains (and/or applications) hosted on the one server and want to keep them running independantly of one another.

The general steps are based loosely on an article in LinuxJournal, however, I have added afew more explanations, corrected a couple of little inaccuracies and added new content to describe the Apache2 mechanism for loading modules and sites.

Pre-installed software

This guide assumes that you have already installed the following applications via apt-get:

• j2sdk1.4
• tomcat5
• apache2
• apache2-threaded-dev
• build-essentials
• a2enmod

Tomcat configuration

Two important environment variables for Tomcat are CATALINA_HOME and CATALINA_BASE. The first one is where the Tomcat files are actually installed (on Ubuntu Dapper Drake, using apt-get, this is /usr/share/tomcat5). The second one is where each running instance of Tomcat looks to find the configuration files and web applications. In the default installation, these variables are set to the same value. What we are going to do is create a directory for each of our webapps, and then start multiple instances of Tomcat with a different CATALINA_BASE for each one.

My suggested location (although I am open to feedback) is to create a new directory called /usr/share/tomcat5/instances that contains your applications. Looking at that containing directory, though, you see something like:

4 drwxr-xr-x   2 root root 4096 2006-08-15 08:02 bin
4 drwxr-xr-x   5 root root 4096 2006-03-19 16:27 common
0 lrwxrwxrwx   1 root root   21 2006-03-23 22:17 conf -> /var/lib/tomcat5/conf
4 drwxr-xr-x   2 root root 4096 2006-03-23 22:17 .debian
0 lrwxrwxrwx   1 root root   14 2006-03-23 22:17 doc -> ../doc/tomcat5
0 lrwxrwxrwx   1 root root   21 2006-03-23 22:17 logs -> /var/lib/tomcat5/logs
4 drwxr-xr-x   5 root root 4096 2006-03-23 22:17 server
0 lrwxrwxrwx   1 root root   23 2006-03-23 22:17 shared -> /var/lib/tomcat5/shared
0 lrwxrwxrwx   1 root root   21 2006-03-23 22:17 temp -> /var/lib/tomcat5/temp
0 lrwxrwxrwx   1 root root   24 2006-03-23 22:17 webapps -> /var/lib/tomcat5/webapps
0 lrwxrwxrwx   1 root root   21 2006-03-23 22:17 work -> /var/lib/tomcat5/work

You will notice that all the actual files are stored in /var/lib/tomcat5 with symbolic links across to them. To keep with this tradition, I used the following commands (all as root):

mkdir /var/lib/tomcat5/instances
ln -s /var/lib/tomcat5/instances /usr/share/tomcat5/instances
cd /usr/share/tomcat5/instances

So, now the base directories have been created, you need to do the initial setup for the Tomcat servers. Run the following commands for your webapp (where myapp is the name of your webapp):

mkdir -p myapp/conf myapp/logs myapp/webapps
cp ../conf/server.xml myapp/conf
cp ../conf/web.xml myapp/conf

Copy your application WAR file into the myapp/webapps directory, and we should be ready to go.

Starting your new instance

We can’t use the original /usr/share/tomcat5/bin/startup.sh to start each instance because it uses the default CATALINA_BASE, so what we do is create a new script file that can start and stop each instance, but pointing to a different CATALINA_BASE. Create a file called /usr/share/tomcat5/instances/myapp/myapp.sh that contains the following:

#!/bin/sh

RETVAL=$?
export JAVA_HOME=/usr/lib/j2se/1.4
export CATALINA_BASE="/usr/share/tomcat5/instances/myapp"
export CATALINA_HOME="/usr/share/tomcat5"
export CATALINA_PID=$CATALINA_BASE/logs/catalina.pid

case "$1" in
 start)
        if [ -f $CATALINA_HOME/bin/startup.sh ];
          then
            echo $"Starting Tomcat"
            exec $CATALINA_HOME/bin/startup.sh
        fi
        ;;
 stop)
        if [ -f $CATALINA_HOME/bin/shutdown.sh ];
          then
            echo $"Stopping Tomcat"
            exec $CATALINA_HOME/bin/shutdown.sh
        fi
        ;;
 *)
        echo $"Usage: $0 {start|stop}"
        exit 1
        ;;
esac
exit $RETVAL

Make sure the original Tomcat instance is stopped (by running sudo /etc/init.d/tomcat5 stop) and start your new instance by typing:

sudo chmod 755 ./myapp.sh
sudo ./myapp.sh start

Now test that Tomcat started up by pointing your browser to port 8180 of your machine with a valid myapp URL.

At this point, all we have really done is to make Tomcat start your application from a different directory. Useful, but not yet where we want to be. We realy want to be able to point the browser to port 80, instead of the non-typical port of 8180. So, we need to configure Apache to hand off to the new running instance using mod_jk.

mod_jk

mod_jk is the means by which Apache hands off incoming HTTP requests to the Tomcat instances. There are two flavours: mod_jk and mod_jk2. Despite what you would think, mod_jk is the more actively developed version and is actually much simpler to install and configure.

In the original version of Apache, you used to have to modify the httpd.conf file, however, with Apache2 things have changed a little. You can still edit /etc/apache2/httpd.conf if you like, but that isn’t the recommended way to configure Apache2. Instead, you will be creating configuration files in the following two directories:

• /etc/apache2/mods-available
• /etc/apache2/sites-available

Before you do that, however, you need to install mod_jk. Download the mod_jk source code, and run the following commands:

tar -xzvf jakarta-tomcat-connectors-1.2.14.1-src.tar.gz
cd jakarta-tomcat-connectors-1.2.14.1/jk/native
./configure --with-apxs=/usr/sbin/apxs2
make
sudo make install

The last command should install a file called mod_jk.so in /usr/lib/apache2/modules. You might want to just quickly check that it is there.

Now, you need to create a file called /etc/apache2/mods-available/jk.load that contains:

LoadModule jk_module /usr/lib/apache2/modules/mod_jk.so

Next, create a file called /etc/apache2/mods-available/jk.conf that contains:

<IfModule mod_jk.c>
  JkWorkersFile       "/etc/apache2/workers.properties"
  JkLogFile           "/var/log/apache2/mod_jk.log"
  JkLogLevel          info
  JkLogStampFormat    "[%a %b %d %H:%M:%S %Y] "
  JkOptions           +ForwardKeySize +ForwardURICompat -ForwardDirectories
  JkRequestLogFormat  "%w %V %T"
</IfModule>

Now, from the command prompt, type the following commands to enable it and become effective. The a2enmod command enables a specific module by creating a symbolic link in /etc/apache2/mods-enabled that points to the equivalent file in /etc/apache2/mods-available directory.

sudo a2enmod jk
sudo /etc/init.d/apache2 force-reload

Nice work. Now you have enabled mod_jk. Now we have to configure a virtual host in Apache to point to our Tomcat instance. You do this by creating a file called /etc/apache2/sites-available/yourdomain.com and adding the following content:

<VirtualHost yourdomain:80>
        ServerAdmin admin@yourdomain.com
        ServerName  yourdomain.com
        ServerAlias www.yourdomain.com

        JkMount /* myapp
</VirtualHost>

This defines a virtual domain that has a Tomcat application called myapp. In fact, the myapp identifier is not actually the application name, but actually references an entry in the workers.properties file (see below). However, while not strictly necessary, if you keep this naming convention it makes it nice and easy to read the configurations when your mod_jk identifiers are the same as your webapp names. The JkMount /* myapp directive instructs Apache to send all urls to Tomcat (via mod_jk). You can, if you choose, a different pattern that more accurately reflects which requests you want Tomcat to handle (for example, JkMount /*.do myapp).

You need to make this new site available for use, so type the following command:

sudo a2ensite yourdomain.com
sudo /etc/init.d/apache2 force-reload

And lastly, we need to tell mod_jk what port Tomcat will be listening on by creating the configuration file that we referenced in /etc/apache2/mods-available/jk.conf. So, create a new file called /etc/apache2/workers.properties that contains:

worker.list=myapp

# Set properties for myapp
worker.myapp.type=ajp13
worker.myapp.host=localhost
worker.myapp.port=8009

The worker.list directive says which of the configurations is available for use. For now, only myapp is available because we have only got one application. This tutorial has Tomcat and Apache on the same machine, so we use localhost as the host. The port that mod_jk will send connections to is 8009, which is the default Tomcat AJP13 listening port. When we add second, and subsequent, applications we will use different port numbers.

Stop and restart Apache by running the following command:

/etc/init.d/apache2 restart

Now, point your browser to your machine, but on port 80 this time. If all has gone well, you should seamlessly get passed through Apache into Tomcat via AJP.

The last thing to do is make Tomcat only accept incoming connections via the AJP connector, instead of allowing connections directly to port 8180 (the HTTP connector). This can be done by editing the myapp/conf/server.xml to comment out the HTTP connector.

<!-- Connector className="org.apache.coyote.tomcat5.CoyoteConnector"
               port="8180" minProcessors="5" maxProcessors="75"
               enableLookups="true" acceptCount="10" debug="0"
               connectionTimeout="20000" useURIValidationHack="false" / -->

Adding second and subsequent webapps

Adding additional webapps is reasonably straightforward. One thing to decide before proceeding is what port numbers to use for your new webapp(s). The default server.xml will have the shutdown port being 8005 and the AJP connector port being 8009. Now, we already know that our first webapp (myapp, in this example) is using those ports, so we need to pick new port numbers. You can pick any port numbers you like, but the convention seems to be 8105/8109 for the second webapp, 8205/8209 for the third, and so on. The required steps are outline below:

1. Run the following commands:
   

   mkdir -p app2/conf app2/logs app2/webapps
   cp ../conf/server.xml app2/conf
   cp ../conf/web.xml app2/conf
   

2. Edit the app2/conf/server.xml, changing these items:
   • Change the port attribute of the <Server> tag from 8005 to 8105.
   • Change the port attribute of the AJP <Connector> tag from 8009 to 8109.
   • Optionally, comment out the HTTP <Connector> tag. If you don’t comment it out (and you didn’t comment it out in myapp/conf/server.xml) you will need to change the value from 8180 to 8181 (or some other port) so that the HTTP connectors of your two webapps aren’t listening on the same port.
3. Edit the /etc/apache2/workers.properties to add new lines that look like:
   

   worker.list=myapp,app2
   
   # Set properties for myapp
   worker.myapp.type=ajp13
   worker.myapp.host=localhost
   worker.myapp.port=8009
   
   # Set properties for app2
   worker.app2.type=ajp13
   worker.app2.host=localhost
   worker.app2.port=8109
   

4. Create a file called /etc/apache2/sites-available/anotherdomain.com and adding the following content:
   

   <VirtualHost anotherdomain:80>
           ServerAdmin admin@anotherdomain.com
           ServerName  anotherdomain.com
           ServerAlias www.anotherdomain.com
   
           JkMount /* app2
   </VirtualHost>
   

5. Enable your new site by running the following commands:
   

   sudo a2ensite anotherdomain.com
   sudo /etc/init.d/apache force-reload
   

6. Copy the myapp/myapp.sh script as app2/app2.sh directory, and modify the line with CATALINA_BASE to point to the app2 directory instead of the myapp directory.
7. Copy your application WAR file into the app2/webapps directory
8. Restart Apache by running /etc/init.d/apache2 restart
9. Start your application by running app2.sh start

Starting automatically

Now, having installed your webapp successfully, you may want to get it to start automatically upon a system restart. The conventional way to do this is to run the following commands:

sudo ln -s /usr/share/tomcat5/instances/myapp/myapp.sh /etc/init.d/myapp.sh
sudo update-rc.d /etc/init.d/myapp.sh defaults 70

Repeat these commands for whichever Tomcat servers you want automatically restarted.

Feedback

If you spot any typos or mistakes, please let me know and I will correct ASAP. Thanks a lot.