Installing Apache Tomcat

Note

Apache Tomcat versions 8.5.x and 9.0.x are supported.

Install Apache Tomcat

Perform the following steps to install Apache Tomcat (download and installation procedure for Apache Tomcat may vary a bit for each platform):
 

Step 1

Select an appropriate method of installation:
 
Windows
We recommend using the GUI installer to create the Apache Tomcat Service:

  1. Download the "32-bit/64-bit Windows Service Installer" from Tomcat 8.5.x or Tomcat 9.0.x.
  2. Follow the instructions to install the package.


Windows or Linux/Unix
Download a tar.gz or zip package that you unzip into a directory:

  1. Download an appropriate package from Tomcat 8.5.x or Tomcat 9.0.x. 
  2. Follow the instructions to unzip the appropriate package (tar.gz or zip) into a directory on your file system.

Linux/Unix: Redhat and Centos distributions
Instead of downloading a tar.gz or zip package, you can use the yum installer.

Step 2

In order to accommodate large workloads, Universal Controller requires that you configure the Java heap size options using the CATALINA_OPTS environment variable. The following table outlines the minimum recommended configuration.
 

z/Linux

CATALINA_OPTS="-Xms512m -Xmx2048m -Xjit:optLevel=noOpt"

All Other Platforms

CATALINA_OPTS="-Xms512m -Xmx2048m"

 
If you have installed Tomcat as a service on Windows, see Windows Service, below; otherwise, see All Platforms:
 
 
All Platforms
 
A recommended way to set the CATALINA_OPTS environment variable is to use the optional setenv script.
 
The script is placed into either the CATALINA_BASE/bin or CATALINA_HOME/bin directory and is named setenv.bat (on Windows) or setenv.sh (on Linux/Unix). The file must be readable.
 

Note

The CATALINA_BASE environment variable specifies location of the root directory of the "active configuration" of Tomcat. It is optional. It defaults to be equal to CATALINA_HOME.

 
By default, the setenv script file is absent. If the script file is present in both CATALINA_BASE and CATALINA_HOME, the file in CATALINA_BASE is preferred.
 
For example, to configure the CATALINA_OPTS environment variable for Java 8, you can create the following script file:
 
On Windows, %CATALINA_BASE%\bin\setenv.bat:
 

set "CATALINA_OPTS=-Xms512m -Xmx2048m"

 
On Linux/Unix, $CATALINA_BASE/bin/setenv.sh:
 

CATALINA_OPTS="-Xms512m -Xmx2048m"

 
For additional Tomcat configuration details, including CATALINA_OPTS, see RUNNING.txt.
 
 
Windows Service
 
If you installed Tomcat as a Windows service, you can set values using the $CATALINA_HOME\bin\tomcatw.exe GUI tool.
 
Enter the parameters as follows (for Tomcat 8.5.x or Tomcat 9.0.x):

  • Initial memory pool = minimum heap size (Xms)
  • Maximum memory pool = Maximum heap size (Xmx)


 

Note

Later, after you start Tomcat and log in to the Controller, you can validate these settings by running the Memory Usage operation, as follows:

  1. From the Administration navigation pane, select Configuration > Server Operations.
  2. Run the Memory Usage operation. The min and max numbers on the top line (Heap) should be similar to the above settings.

Start and Validate Apache Tomcat

Perform the following steps to start and validate Apache Tomcat:

Step 1

Tomcat is normally run as a system service or daemon. You can start Tomcat using the standard method for your operating system or by using a script, as follows:
 
Windows
Use Windows Services to start Tomcat or start Tomcat from the command line as follows: net start <name of Tomcat service>.
 
Linux
Start the Tomcat daemon using the script placed in the /etc/init.d directory for Tomcat: service <name of Tomcat service> start.
 
Windows or Linux
Start the service using the $CATALINA_HOME/bin/startup.bat or $CATALINA_HOME/bin/startup.sh scripts.

Step 2

Open a browser and go to the following URL: http://localhost:8080.

Step 3

The following screen displays, verifying that you have successfully installed and started Tomcat:
 

Troubleshooting

Tomcat Post Limit: STATUS_MAX_POST_SIZE_EXCEEDED

Problem

The following error message displays:

The server did not receive the data that was sent to it. Please see the documentation for isc.RPCResponse.STATUS_MAX_POST_SIZE_EXCEEDED

Resolution

Remove the post limit by specifying the following attribute on the <Connector> element in conf/server.xml:

maxPostSize="-1"

Special Characters Not Displaying Correctly

Problem

Some special characters not getting displayed correctly in your browser GUI.

Resolution

Tomcat on Windows requires you to define code page UTF-8 as the default code page for war files.

To do this, add the following to the Java options statement just as you did with the memory parameter:

-Dfile.encoding=UTF8