Tomcat

TODO: add info on logs, environment variables

Basics

Tomcat is the server program responsible for providing the interactive interface of the e-Labs. Technically, it's a Java "Servlet Container." In more modern terms, it's something like an early Java web framework that converts Java ServerPages (JSP) files and special Java files called "Servlets" into HTML.

Usage

Tomcat runs on the main server VMs i2u2-prod and i2u2-dev, which use the Ubuntu OS. If you set up a local development environment, you'll also need to run Tomcat on your machine. We recommend Ubuntu for this for consistency, though we have some experience using OS X/macOS.

On all systems, Tomcat can be manipulated through its included catalina.sh script

OS	location
Ubuntu 14-20	/usr/share/tomcat{X}/bin/catalina.sh
OS X El Capitan	/usr/local/apache-tomcat-{X}/bin/catalina.sh

(Replace {X} with the appropriate version for your situation) with the commands

$ sudo /path/to/catalina.sh (start | stop | version)

However, Ubuntu has shortcut commands that you'll use more frequently.

Tomcat on Linux

We've installed and used various versions of Tomcat on Ubuntu 14, Ubuntu 16, and Fedora 23 Linux. Ubuntu usually refers to Tomcat using its version number: tomcat7, tomcat8, e.g., while Fedora drops the number, using simply tomcat. Otherwise there's little difference between the two.

Ubuntu 14.04 runs Tomcat as a System V service (called Upstart), meaning that there will exist a directory /etc/init.d/ containing control scripts (/etc/init.d/tomcat{X}/ for Tomcat) that streamline interaction with its processes. These are accessed with commands such as

$ sudo service tomcat{X} (start | stop | status | restart)

You may also see people accessing the init scripts directly with

$ sudo /etc/init.d/tomcat{X} (start | stop | status | restart)

though there's not really any good reason to do this as far as I can tell.

Ubuntu 16.04 (and higher) and Fedora 23 use the newer systemd structure with systemctl syntax,

$ sudo systemctl (start | stop | status | restart) tomcat.service

The /etc/init.d/ directories continue to exist on both Ubuntu (up to 20.04, at least) and Fedora 23, and the older System V service commands still work on both, but they redirect to systemd commands. Expect the System V structure to disappear in the next few years with future versions of these distributions.

Tomcat on OS X (El Capitan)

The catalina.sh script commands

$ sudo /usr/local/apache-tomcat-{X}/bin/catalina.sh (start | stop | version)

can be used to manage Tomcat, with the meaning of each option hopefully obvious. You can add the script's directory to your PATH variable for convenience; otherwise you'll need to specify the absolute filepath when you invoke it.

The directory /usr/local/apache-tomcat-{X}/ is what we symlink as ~/quarkcat/sw/tomcat when setting up a local development environment, so you'll also be able to use

$ sudo ~/quarkcat/sw/tomcat/bin/catalina.sh (start | stop | version)

This is the only practical way to work with Tomcat on OS X. Note that catalina.sh doesn't have a restart command. To restart, you'll have to use stop and then start in succession. There's also no status command; to see if Tomcat is running from the command line, use

$ ps aux | grep catalina

($ ps aux | grep tomcat should also work). A running Tomcat process will be a lengthy entry ending in org.apache.catalina.startup.Bootstrap start.

Directories and Settings

This section is limited to the file structure and settings files of Tomcat on Ubuntu.

Webapp Files

The Tomcat "server" directory is /var/lib/tomcat{X}/webapps/. By default, Tomcat considers any folder within this directory to be a webapp. For example, the directory /var/lib/tomcat{X}/webapps/elabs/ is the e-Labs webapp; files within this folder are the "live" files used to deliver the e-Labs to the user's browser.

On the server VMs (and on a local development environment), we symlink the folder /var/lib/tomcat{X}/ to ~quarkcat/sw/tomcat/. I'm not certain if there's a technical reason for this, but it does conveniently make all the e-Labs files you need to work with available within the ~quarkcat/ user directory at ~quarkcat/sw/tomcat/webapps/elabs/.

Server Settings

Global settings for Tomcat are contained in the server.xml file at /etc/tomcat{X}/server.xml

-- Main.JoelG - 2016-05-05

Comments

</verbatim>