Skip to main content

Manage Tomcat Applications

Apache Tomcat is an open-source Java application server that runs Java Servlets, JSPs, and web applications.

With our best-practice configuration, you get a Tomcat installation that can be managed directly by the www-data user. This allows for greater flexibility in configuring instances without requiring you to keep them up to date yourself.

This page guides you through setting up your own Tomcat instance with a reverse proxy:

Requirements​

  • Tomcat configured by us on your server (contact us to install it: )
  • nine-manage-vhosts installed on the server

Creating a Tomcat Instance​

info

In this example, Tomcat 10 is used. Adjust the command based on your installed Tomcat version.

You can find the version available on your server by running the following command:

apt search --names-only 'tomcat[0-9]+-user'

Create a new Tomcat instance by running tomcat10-instance-create. The following parameters can be provided:

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

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

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

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

Making Tomcat applications accessible​

Tomcat listens on localhost by default. A reverse proxy is commonly used to make the application accessible via a public URL. To set up this reverse proxy, use nine-manage-vhosts.

The following command creates a vhost named test-server.ch that forwards all traffic to the Tomcat instance on port 8081:

sudo nine-manage-vhosts virtual-host create test-server.ch --template=proxy --template-variable PROXYPORT=8081
info
  1. The Tomcat template assumes all instances are located under /home/www-data/<domain-name>.
  2. To use a Let's Encrypt certificate and HTTPS, set the template proxy_letsencrypt_https instead of proxy.
  3. To automatically redirect HTTP to HTTPS using a Let's Encrypt certificate, use the template proxy_letsencrypt_https_redirect.

The dedicated documentation contains more examples and details about the usage of nine-manage-vhosts.

Starting the Tomcat instance automatically​

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

To ensure the instance launches on server boot, run:

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

The following commands manually start or 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
info

  1. The first part of the service name remains user-tomcat@. The part after @ is your Tomcat instance name.

  2. If you have multiple Tomcat versions installed, you can specify the desired version in the service file like this user-tomcat10@test-server.ch:

For more information on managing services with systemd, refer to Manage Daemons as a User With Systemd.

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​

Applications are typically packaged as .war or .jar files.

Deployment location​

The application should be located in /home/www-data/<vhost-name>/ROOT.

To run multiple applications in one virtual host, place each application in its own directory under /home/www-data/<vhost-name>/webapps. Applications are then accessible at http://servername.com/name_of_the_folder_in_webapps/.

Example​

To deploy test-application.war to the test-server.ch instance, this could be used:

rsync --progress test-application.war www-data@server.nine.ch:~/test-server.ch/webapps/

Tomcat then extracts it to:

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

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

Logging​

If your application logs to standard output, logs are written to /home/www-data/<instance-name>/logs/catalina.out.

warning

The catalina.out log file can grow quickly. Follow this guide to set up scheduled log rotation and avoid disk space issues.

Environment variables​

Tomcat's behavior cab be modified by setting environment variables in ~/<instance-name>/bin/setenv.sh.

Examples​

  • Using a different Java version:

    JAVA_HOME="/opt/java/production"

  • Changing log location:

    CATALINA_OUT="logs/custom.out"

  • Adjusting memory limits:

    JAVA_OPTS="-Djava.awt.headless=true -Xmx512M ${JAVA_OPTS}"
    info

    The default memory limit for the instance is set to 128MB. When adjusting this value, ensure that the new limit is a multiple of 1024 and is at least 2MB.

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.

To apply settings for all instances, place the file in:

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

To modify settings for a single instance, place the file in:

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

For example, to set the Max Open Files limit, create the following file:

~/.config/systemd/user/user-tomcat@test-server.ch.service.d/limits.conf
[Service]
LimitNOFILE=2048