How to manage Tomcat 8 + 9 instances

Tomcat is an application server to run Java applications.

With our Tomcat Service, you get a Tomcat 8 or 9 installation that can be managed directly by the www-data user. This means more flexibility in the configuration of the instances, without having to keep them up-to-date yourself.

Step by step guide

You can skip this section if you migrated from a Tomcat 6 managed solution, as we have done all that for you already.

In this section, we will guide you through the (rather short) process of setting up your own Tomcat instance with a reverse proxy.

Requirements

• Ubuntu 16.04 Xenial (tomcat8) or 18.04 Bionic (tomcat9)
• Tomcat 8 or 9 configured by us on your server (contact us to install it: Support)
• nine-manage-vhosts installed on the server

Creating a Tomcat instance

We will use the tomcat8-instance-create or tomcat9-instance-create tool (official tomcat8 documentation) or (official tomcat9 documentation) to create our Tomcat instances. A few parameters should be provided:

HTTP port (defaults to 8080) Control port (defaults to 8005)

The following command will create a tomcat instance in the folder ~/test-server.ch on port 8081 with control port 8006:

tomcat8-instance-create -p 8081 -c 8006 ~/test-server.ch

tomcat9-instance-create -p 8081 -c 8006 ~/test-server.ch

Remarks

1. When creating multiple tomcat instances, you need to ensure that the HTTP port and the control port are unique.

Making Tomcat accessible to the outside world with a reverse-proxy

Tomcat listens on localhost by default. It is common practice to place a reverse-proxy in front of Tomcat. We will use nine-manage-vhosts to create that reverse-proxy.

The following command will create a vhost named test-server.ch that will forward all of its traffic to the Tomcat instance on port 8081:

sudo nine-manage-vhosts virtual-host create test-server.ch --template=proxy --template-variable PROXYPORT=8081

Remarks

1. We assume in the Tomcat template that all of the Tomcat instances are located under /home/www-data/<domain-name>.

2. To make use of a Let's Encrypt certificate and https you can set the template proxy_letsencrypt_https instead of proxy.

3. (only needed with apache): To automatically redirect from http to https with using a Let's Encrypt certificate, you can set the template proxy_letsencrypt_https_redirect.

Start the Tomcat instance on system startup

We provide a default systemd template to start/stop your Tomcat instances.

The first thing we need to do is to ensure that the instance will be launched on server boot with the following command:

systemctl --user enable user-tomcat@test-server.ch

The next commands will start/stop the Tomcat instance named test-server.ch:

systemctl --user start user-tomcat@test-server.ch
systemctl --user stop user-tomcat@test-server.ch

To check the current status of the Tomcat instance, you can use the following command:

systemctl --user status user-tomcat@test-server.ch

Remarks

1. The first part of the service name is unchanged : user-tomcat@. What comes after the @ is your Tomcat instance name.

For more information about managing services with systemd, please refer to this article.

Putting it all together

The following commands will setup a tomcat installation accessible from http://test-server.ch :

# Create the Tomcat instance, accessible on http://localhost:8081
tomcat8-instance-create -p 8081 -c 8006 ~/test-server.ch

# Add a reverse proxy for Tomcat to make it accessible from the outside.
sudo nine-manage-vhosts virtual-host create test-server.ch --template=proxy --template-variable PROXYPORT=8081

# Deploy your application to the instance (see below).
[...]

# Make the instance launch on boot
systemctl --user enable user-tomcat@test-server.ch

# Start the Tomcat instance.
systemctl --user start user-tomcat@test-server.ch

Deploying your application

In this section, you will deploy your Java application to the Tomcat instance. Below are a few things to know about the deployment process:

Application format

An application usually has the form of a .war or .jar file.

Where to put the application?

An application must be copied to /home/www-data/<vhost-name>/ROOT.

There is also the possibility to run multiple applications in one virtual host. For that, every application needs its own directory under /home/www-data/<vhost-name>/webapps. The applications are then accessible at "http://servername.com/name_of_the_folder_in_webapps/".

Deployment example

Let's say we have the same Tomcat instance as before: test-server.ch.

We want to deploy our application test-application, that we currently have as a war file: test-application.war.

cp test-application.war /home/www-data/test-server.ch/webapps/

# Tomcat will extract it to a folder called "test-application":
# /home/www-data/test-server.ch/webapps/test-application

The application is accessible at http://test-server.ch/test-application, and its logs are under /home/www-data/test-server.ch/logs/catalina.out.

Where does it log?

If your applications log to the standard output, the logs will be written in /home/www-data/<instance-name>/logs/catalina.out.

Please bear in mind that your catalina.out will grow big quickly with this method, and that it is recommended to use a logging utility instead of the standard output.

If you still want to use STDOUT in your application for logging purposes, there are two things you should do:

1. Disable the log rotation in Tomcat, because it is not rotating the logs properly. This can be done by editing the file conf/logging.properties and add following lines:

1catalina.org.apache.juli.FileHandler.rotable = false
2localhost.org.apache.juli.FileHandler.rotable = false

2. Configure a proper log rotation.

Additional information

For more information on deployment, please refer to the official documentation.

Advanced configuration

Since the tomcat instances are managed by www-data, you can change all the configuration you need without using sudo or contacting nine (see the official documentation tomcat8 or official documentation tomcat9 as a reference).

This being said, we would like to show you some common configuration tweaks, and we do them via environment variables.

Environment variables

Some parts of the behaviour of Tomcat can be controlled by setting some environment variables in the file ~/<instance-name>/bin/setenv.sh

Below are some examples of what can be changed using them:

Using a different Java version

Add the following to the setenv.sh file and restart your instance to switch the current java version:

JAVA_HOME=/opt/java/production

Change the output log location

Add the following to the setenv.sh file and restart your instance to log to a different file:

CATALINA_OUT=logs/custom.out

Change the maximum amount of memory

The tomcat8-instance-create and tomcat9-instance-create script sets in setenv.sh a default of 128MB of memory for a given instance. Just replace the 128MB with the value of your choosing (must a multiple of 1024 greater than 2 MB).

For instance, the following would allow your instance to use at most 512MB of memory:

if [ -z "$JAVA_OPTS" ]; then
        JAVA_OPTS="-Djava.awt.headless=true -Xmx512M"
fi

Systemd settings

Some parameters can not be set by Tomcat but rather need to be set by systemd. Those settings can be modified by so-called systemd drop-ins.

They can be set either for all instances of a user or for a specific instance.

To modify the configuration for all instances, place the file in

~/.config/systemd/user/user-tomcat@.service.d

To only modify a single instance, place the file into

~/.config/systemd/user/user-tomcat@<instance-name>.service.d

For example, to set the Max Open Files limit, drop this file into one of the folders mentioned above:

# nofiles.conf

[Service]
LimitNOFILE=2048