Introduction

Apache Tomcat is the java web server which runs the PhixFlow web application.

This guide covers downloading and installing Tomcat 9 on a linux server.

Prerequisites

The following instructions assume that:

• you can login as a non-root user with sudo access.
• you have installed Java, with the required settings.

Step 1  Create Tomcat user

This is the tomcat user (in the tomcat group).

We set the shell to /bin/false so that it is not possible to login as tomcat, and set the home directory to /opt/tomcat, the directory under which we will install tomcat.

This user will own all files created by PhixFlow and must be able to read all PhixFlow-specific files and directories.

sudo groupadd tomcat
sudo useradd -s /bin/false -g tomcat -d /opt/tomcat tomcat

Step 2  Download and install Tomcat 

1. Download

   1. To find the latest version, go to the Tomcat downloads page: https://tomcat.apache.org/download-90.cgi
   2. Find the latest Binary Distributions section, then the Core sub-heading, and copy the tar.gz link.

   3. To download Tomcat, on the Linux server, go to the tmp directory. Use the curl command to download from the the tar.gz link.

      cd /tmp
      curl -O http://mirror.ox.ac.uk/sites/rsync.apache.org/tomcat/tomcat-9/v9.0.38/bin/apache-tomcat-9.0.38.tar.gz

2. Install

   1. Unpack the Tomcat tar.gz file into /opt/tomcat.

      sudo mkdir /opt/tomcat
      cd /opt/tomcat
      sudo tar xvf /tmp/apache-tomcat-9*tar.gz --strip-components=1

      This creates the tomcat folders (conf, logs, webapps etc.) directly under /opt/tomcat.

   2. Set the file ownership and permissions.

      cd /opt/tomcat
      sudo chown -R tomcat webapps/ work/ temp/ logs/
      sudo chgrp -R tomcat .
      sudo chmod -R g+r conf
      sudo chmod g+x conf

Step 3  Create a service wrapper

This step creates a wrapper that allows Tomcat to be managed as a service. Using a service means you can stop and start Tomcat reliably, and ensures that the running environment (e.g. the starting directory) is well defined.

These instructions create a systemd service.

First, create a service definition file:

sudo vi /etc/systemd/system/tomcat.service

And then paste the following script into the file, making sure that the script is adjusted so that: 

• JAVA_HOME is the base installation of Java. If you don't know where this is, run the command:

update-alternatives --list java

This will give you the full path of the java program, for example: /usr/lib/jvm/temurin-11-jdk-amd64/bin/java. The installation directory in this case is /usr/lib/jvm/temurin-11-jdk-amd64.

• The memory settings (-Xms and -Xmx) on the line for CATALINA_OPTS are set as needed (this example assumes you are allocating 8GB of memory to tomcat); see Tomcat Planning for details of estimating Tomcat's memory allocation
• The location of the GC (Garbage Collection) log file, set in CATALINA_OPTS, is correct - in the examples below, this /opt/tomcat/logs

Java 8

[Unit]
Description=Apache Tomcat Web Application Container
After=network.target

[Service]
Type=forking

Environment=JAVA_HOME=/usr/lib/jvm/temurin-8-jdk-amd64
Environment=CATALINA_PID=/opt/tomcat/temp/tomcat.pid
Environment=CATALINA_HOME=/opt/tomcat
Environment=CATALINA_BASE=/opt/tomcat
Environment='CATALINA_OPTS=-Xms8096M -Xmx8096M -server -XX:+PrintGCDetails -XX:+PrintGCDateStamps -Xloggc:/opt/tomcat/logs/gc-%%t.log'
Environment='JAVA_OPTS=-Djava.awt.headless=true'

ExecStart=/opt/tomcat/bin/startup.sh
ExecStop=/opt/tomcat/bin/shutdown.sh

WorkingDirectory=/opt/tomcat

User=tomcat
Group=tomcat
UMask=0007
RestartSec=10
Restart=always

[Install]
WantedBy=multi-user.target

Java 11

[Unit]
Description=Apache Tomcat Web Application Container
After=network.target

[Service]
Type=forking

Environment=JAVA_HOME=/usr/lib/jvm/temurin-11-jdk-amd64
Environment=CATALINA_PID=/opt/tomcat/temp/tomcat.pid
Environment=CATALINA_HOME=/opt/tomcat
Environment=CATALINA_BASE=/opt/tomcat
Environment='CATALINA_OPTS=-Xms8096M -Xmx8096M -server -Xlog:gc=debug:file=/opt/tomcat/logs/gc-%%t.log:time,uptimemillis,tid'
Environment='JAVA_OPTS=-Djava.awt.headless=true'

ExecStart=/opt/tomcat/bin/startup.sh
ExecStop=/opt/tomcat/bin/shutdown.sh

WorkingDirectory=/opt/tomcat

User=tomcat
Group=tomcat
UMask=0007
RestartSec=10
Restart=always

[Install]
WantedBy=multi-user.target

Now enable, then start the service:

sudo systemctl daemon-reload
sudo systemctl start tomcat

Lastly, check that the service started:

sudo systemctl status tomcat

Conclusion

From this point on, tomcat will start automatically when the host restarts, and you can re-start tomcat manually like this:

sudo systemctl restart tomcat