Tomcat 8 on Debian Jessie with PSI Probe and OpenNMS to monitor performance (Part 1)

This is the first of three posts about the latest version of Apache Tomcat, still the most widely used application server, on Debian Jessie, with PSI Probe to manage it and OpenNMS to monitor its up-time.

What's new in Tomcat 8?

Debian Jessie was released with Apache Tomcat 8, which provides the following:

• Java Servlet 3.1, an incremental release of the servlet specification that includes non-blocking I/O to improve scaleability and an HTTP protocol upgrade mechanism that allows the client and the server to negotiate a transition from HTTP 1.1 to some other new chosen protocol;
• JavaServer Pages 2.3, a maintenance release to provide support for Expression Language (EL) 3.0 and to use the functionality of the Servlet 3.1 API;
• Java Unified Expression Language (EL) 3.0, which allows EL to run in a standalone mode outside of servlets or JSPs, plus lambda expressions and other Java 8 goodies;
• WebSocket 1.1, which allows full duplex communications over TCP so that bidirectional data can flow at the same time;
• A single, common resources implementation that merges Aliases, VirtualLoader, VirtualDirContext, JAR resources and external repositories into a single framework rather than a separate one for each feature;
• and Java EE 7 as a minimum pre-requisite, preferably Java EE 8, which has better support for HTML5, WebSockets, JSON and RESTful services.

Tomcat 8 is more flexible and better equipped to support web services than its predecessor, so let's proceed to the upgrade.

Installing Tomcat 8

Installing Tomcat 8 on Debian Jessie is dead simple. First, SSH to your web server (called 'my-server-IP' here) as root, and  execute 'java -version' to check that OpenJDK 7 is installed as a minimum:

# java -version
java version "1.7.0_79"
OpenJDK Runtime Environment (IcedTea 2.5.5) (7u79-2.5.5-1~deb8u1)
OpenJDK 64-Bit Server VM (build 24.79-b02, mixed mode)

If you don't see OpenJDK 7, you will have to install it and set it to be the default JVM:

# apt-get install openjdk-7-jdk openjdk-7-demo openjdk-7-source
# update-alternatives --config java

If you prefer, you can install OpenJDK 8 from the jessie-backports repository instead of OpenJDK 7, but it makes no difference to Tomcat 8.

Now install Tomcat 8:

# apt-get install tomcat8 tomcat8-admin tomcat8-docs tomcat8-examples tomcat8-user 

If all goes well, the service should start automatically and you should be able to browse to http://my-server-IP:8080 to see the default page:

Configuring Tomcat 8

Once you have installed Tomcat 8, you must enable the manager webapp, and you may optionally tune the JVM memory settings.

Edit /etc/tomcat8/tomcat-users.xml to include a manager (called 'my-user' here), with the appropriate roles to use the web console manager:

# vi /etc/tomcat8/tomcat-users.xml
<tomcat-users>
   <role rolename="manager-gui"/>
   <role rolename="admin-gui"/>
   <user username="my-user" password="my-user-password" roles="manager-gui,admin-gui"/>
</tomcat-users>

The manager-gui role has the highest privileges, allowing you to use the web console manager to deploy and undeploy apps, view stats, generate leak detection diagnostics, expire sessions, and so on. The admin-gui role is needed to access the virtual host manager.

Optionally edit the default Tomcat 8 configuration to make sure that JAVA_HOME is correctly set and to tune the performance of the JVM:

# vi /etc/default/tomcat8
JAVA_HOME=/usr/lib/jvm/java-7-openjdk-amd64
JAVA_OPTS="-Djava.awt.headless=true -Xms2048m -Xmx2048m -XX:+UseConcMarkSweepGC"

Now restart Tomcat 8, using the systemd way of managing services:

# systemctl restart tomcat8

and browse to http://my-server-IP:8080/manager.

Login with the username you created in tomcat-users.xml to access the Web Application Manager, an eye-watering horror of mustard and green that we will quickly replace with PSI Probe in Part 2 of this series, a much better-looking web console manager with a raft of extra functionality.

Location of Tomcat 8 directories on Debian

Note that the Debian package maintainers have a standard Debian way of doing things so the Tomcat 8 directories may not be where you expect them to be. The relevant locations are:

/etc/default: the initial default settings such as the Tomcat user ID, JAVA_HOME, JVM settings, and so on, are in the file 'tomcat8'.

/etc/tomcat8: the server configuration files are here, including context.xml, server.xml and tomcat-users.xml.

/etc/logrotate.d: the log settings for catalina.out are in the file 'tomcat8'.

/usr/share/tomcat8: this is $CATALINA_HOME, the root of the Tomcat installation, also known as $TOMCAT_HOME. It has startup, shutdown, and other scripts, as well as the Tomcat JARs in $CATALINA_HOME/lib (the original project to develop the servlet engine was called Catalina).

/var/lib/tomcat8: this is $CATALINA_BASE, also known as $TOMCAT_BASE, which holds instance-specific directories for web applications, with the code in $CATALINA_BASE/webapps.

/var/log/tomcat8: all the log files are stored here.

Now stay tuned for the installation of PSI Probe in Part 2.