Using Personal Tomcat in DoC

A Little Tomcat History

For several years, we attempted to build and maintain shared Tomcat servers, which many users could use to develop JSP and servlet webapps in parallel. However, they were always unreliable, and we have concluded that Tomcat's fundamental design is not suited to the teaching environment, where many users rapidly create contexts, update web content, break things etc.

We have recently decommissioned the last remaining shared Tomcat web server (www-jsp.doc.ic.ac.uk), and we will not be replacing it.

Personal Tomcat at DoC

Instead, therefore, we have provided (and strongly recommend) something we call Personal Tomcat: every summer, we download the latest binary version of Apache Tomcat (currently version 7.0.29 as of Oct 2012), package it and install it on every DoC linux lab machine. However, we do not arrange for Tomcat to have any configuration, and we certainly don't arrange for it to start automatically. That's something you need to do - hence, it's a private and personal Tomcat system for you to experiment with.

• The basic idea is that you can create any directory you like as a Personal Tomcat context directory via the command:

mktomcat8 ~/example-context

• Note that this creates the directory ~/example-context (it must not already exist) and populates it with standard Tomcat configuration information.

• We strongly recommend that such personal tomcat dirs should not be inside your ~/public_html directory, as that allows Apache to serve out the source code and other private stuff, which might reveal database passwords etc by accident. Also, spaces in the Tomcat context directory name breaks the tomcat8 start script!

• Next, cd ~/example-context and look around - especially read the README file which describes everything in considerable detail. The rest of this web page covers essentially the same material as the README file does!

• Inside ~/example-context, you can add your web content and alter Tomcat configuration settings as much as you like. Here's a few hints:

  • You can add JSP pages and plain web pages (and images etc) into web-apps/ROOT (you'll find an index.jsp file already in there, containing some content as an example).

  • You can install Java jar files (including java bean jar files) into web-apps/ROOT/WEB-INF/lib.

  • You can install Java class files into web-apps/ROOT/WEB-INF/classes.

  • You can edit the URL to servlet mappings in web-apps/ROOT/WEB-INF/web.xml.

  • You can even edit the Tomcat config in conf/server.xml: This allows you to - for instance - change the port that Tomcat will start on, set to 59999 by default, or make Tomcat start up with https support instead.

• When you want to start tomcat on your current desktop machine (suppose you're using ray18) for a few minutes in order to test your JSP code or servlets, make sure that your current working directory is still ~/example-context via pwd, and then say:

      tomcat8 start

• Assuming that Tomcat has started ok (read the logs in the logs subdir, see the README for details), point your web browser at:

      http://localhost:59999/index.jsp

• Note: Here, obviously, if you choose a different port then replace 59999 with your chosen port no.
• Now you should see index.jsp rendered in the web browser - presenting your web content, or if it's the default file, you'll see a 2D table of grey boxes saying hello! You can interact with the web browser testing your web app out as much as you like.
• Finally (IMPORTANT!!! DON'T FORGET THIS STEP!) as soon as your tests are complete - before logging out, or even changing things - you MUST:

      tomcat stop

• This system gives you a much better level of control, it's only your web app running, so no interference is possible, you even get to modify the config files, and you choose when to start and stop tomcat.
• You could even set up several personal tomcat webapp directories, to test different servlets, web-apps, or versions of a complex system as you build it.

How to do I find out what's Wrong?

When things don't work with Personal Tomcat, as with all versions of Tomcat, you'll see an incomprehensable Java stacktrace as the web page result. Tomcat also writes useful debugging information into various files in the logs subdirectory - Tomcat logs are famed for their beauty and helpfulness [sarcasm], but they're all you've got!

As the Tomcat configuration is under your control, another debugging approach Tomcat experts may be able to use is to modify the config to make Tomcat start in some kind of debugging mode.

Note: we have recently noticed that choosing a contact directory name containing spaces causes the tomcat8 script to fail to start. Filenames with spaces in them are just wrong in any universe, so just don't do it!

Recap: How to Setup a Personal Tomcat Context Directory

To recap, here's the procedure to create a new Context directory called my-context for us to work in:

• mktomcat8 ~/my-context

• cd ~/my-context

• tomcat8 start

• Point a web browser at: http://localhost:59999/index.jsp and you should see the output of the index.jsp file, with it's 2D array of grey boxes.

• tomcat8 stop

• Right, now you're ready to start developing some content of your own!

More Detailed JSP and Servlet Examples

For some more information on JSP and Servlets, see the following documents:

• JSP Tutorial

• Servlet Tutorial

Authenticated access to JSP and Servlets

• We do not know how to set up secure authenticated web pages using Tomcat.
  • A past student once wrote some documentation describing how a plain Java program can use the Kerberos authentication libraries to work with users and College passwords, we have no idea how to do that with Tomcat.

• here's the student-contributed Java and kerberos documentation