Applicable Plans - All Cloud Hosting Plans

Tomcat Installation and Tuning

Overview

Using the eApps Virtual Cloud Server Hosting service, Java SE 7 or Java SE 8, and the Apache Tomcat Application Server, you can create web sites and web applications with dynamic content for your customers and users.

This User Guide is designed to help you install Java and Tomcat on your Virtual Server, and to do basic tuning if necessary.

Information on how to actually deploy your applications using one of the supported deployment methods: Tomcat with the Apache Web Server or Tomcat without the Apache Web Server, are found in the User Guides specific to that method:

• Tomcat Application Deployment with Apache Web Server

• Tomcat Application Deployment without Apache Web Server

Pay careful attention to the resources allocated to your Virtual Server when deploying Tomcat applications, especially the available RAM. Tomcat can be very memory intensive, and a lack of resources is one of the main reasons for poor performance. For a small Tomcat application, start with at least 768 MB of RAM, and be prepared to scale upwards as necessary. For larger Tomcat applications, start with at least 1024 MB of RAM, and again be ready to scale upwards if your traffic and resource needs demand it.

This user guide uses the generic TomcatX or tomcatX to refer to Tomcat versions. Please make sure to substitute your version of Tomcat for X (either Tomcat6/tomcat6, Tomcat7/tomcat7, or Tomcat8/tomcat8) where applicable.

Installing Tomcat
    Installing Tomcat using a Control Panel
    Installing Tomcat using the command line

Starting and Stopping Tomcat
    Using the Control Panel
    Using the Command line

Tomcat Application deployment

Tomcat Manager
    Enabling Tomcat Manager
    Accessing Tomcat Manager

Tuning Tomcat
    Java Heap Settings – an overview
    Use Database Connection Pooling (DBCP) When Necessary

Installing Tomcat

There are two choices for installing Tomcat:

1. You can use the one of the existing Tomcat templates when you create your Virtual Server, which will install Tomcat, Java SE 8, and mod_jk.

2. You can create your Virtual Server with one of the CentOS ISPmanager CP templates, and install Tomcat and related applications individually. To run Java applications using Tomcat, you will need to install your preferred version of Tomcat and Java SE 7 or Java SE 8 (either version of Java will work). Install Java SE 7 or Java SE 8 (whichever one you are going to use) first.

For either installation choice, you will need to install a database and a database connector (JDBC). Which databases are available will depend on your OS Template (CentOS 6 or CentOS 7).

• CentOS 6 - either MySQL or PostgreSQL is available to install.

• CentOS 7 - either MariaDB or PostgreSQL is available to install. MySQL must be installed from the official MySQL Community repo or a third-party repo (this is explained in the MySQL user guide).

You will also need to install either the MySQL JDBC Driver for MySQL or MariaDB, or the PostgreSQL JDBC Driver for PostgreSQL. This is explained in the user guide for each database.

If you are going to use the mod_jk deployment method (used by the majority of eApps customers), you will need to install mod_jk. If you are going to use the mod_proxy_ajp deployment method, nothing additional needs to be installed because mod_proxy_ajp is an Apache module, and is available if Apache is installed.

Installing Tomcat using a Control Panel

Installing Tomcat using the ISPmanager Control Panel

If you are using the ISPmanager Control Panel, you can install Tomcat and related applications from that Control Panel.

• For ISPmanager 4, go to Server Settings > Applications. Make sure to install Java SE 7 or Java SE 8 first, then install Tomcat and any other related applications. More information on installing applications can be found here - Installing Server Applications

• For ISPmanager 5, go to Settings > Features. Make sure to install Java SE 7 or Java SE 8 first, then install Tomcat and any other related applications. More information on installing applications can be found here - Installing Features (Server Applications)

Information on how to tell which version of ISPmanager you are using can be found here - ISPmanager versions

Installing Tomcat using the command line

You can install Tomcat and related applications from the command line of the Virtual Server. You will need to install either Java SE 7 or Java SE 8 and several Java plugins first, and then install Tomcat. All of this is done using yum.

To install Java SE 7 and the related applications, use the yum install -y java-1.7.0-sun java-1.7.0-sun-plugin java-1.7.0-sun-jdbc java-1.7.0-sun-src java-1.7.0-sun-devel java-1.7.0-sun-javafx command.

[root@eapps-example ~]# yum install -y java-1.7.0-sun java-1.7.0-sun-plugin java-1.7.0-sun-jdbc java-1.7.0-sun-src java-1.7.0-sun-devel java-1.7.0-sun-javafx

To install Java SE 8 and the related applications, use the yum install -y java-1.8.0-oracle java-1.8.0-oracle-plugin java-1.8.0-oracle-jdbc java-1.8.0-oracle-src java-1.8.0-oracle-devel java-1.8.0-oracle-javafx command.

[root@eapps-example ~]# yum install -y java-1.8.0-oracle java-1.8.0-oracle-plugin java-1.8.0-oracle-jdbc java-1.8.0-oracle-src java-1.8.0-oracle-devel java-1.8.0-oracle-javafx

To install Tomcat, use the yum install -y tomcatX command, where "X" is the version of Tomcat you want to install (Tomcat 6, 7, and 8 are available).

[root@eapps-example ~]# yum install -y tomcatX

If you are going to use the mod_jk approach for Tomcat, you will need to install mod_jk using the yum install -y mod_jk.

[root@eapps-example ~]# yum install -y mod_jk

If you are going to install your database from the command line, please see the specific user guide for that database:

• Instructions for installing and configuring MariaDB and phpMyAdmin from the command line are in the MariaDB User Guide

• Instructions for installing and configuring MySQL and phpMyAdmin from the command line are in the MySQL User Guide

• Instruction for installing and configuring PostgreSQL and phpPgAdmin from the command line are in the PostgreSQL User Guide

Starting and Stopping Tomcat

Using the Control Panel

Using ISPmanager

The way to start, stop, and restart Tomcat from ISPmanager will depend on which version of ISPmanager you are using. Make sure to substitute your version of Tomcat for TomcatX.

• For ISPmanager 4, go to Management Tools > Services, and highlight the TomcatX service. Then click on Stop, Start, or Restart in the upper right corner. More information about managing service in ISPmanager 4 is available here - Managing Services

• For ISPmanager 5, go to System > Services, and highlight the TomcatX service. Then click on Start, Stop, or Restart in the upper left corner. More information about managing services in ISPmanager 5 is available here - Managing Services

Using the Command line

To stop, start, or restart Tomcat from the command line, you will need to log in to the Virtual Server using SSH, and be able to work as the root user.

• For CentOS 6, use the service tomcatX stop, service tomcatX start, and service tomcatX restart commands, where X is your version of Tomcat.

  [root@eapps-example ~]# service tomcatX stop
  [root@eapps-example ~]# service tomcatX start
  [root@eapps-example ~]# service tomcatX restart

• For CentOS 7, use the systemctl stop tomcatX, systemctl start tomcatX, and systemctl restart tomcatX commands, where X is your version of Tomcat.

  [root@eapps-example ~]# systemctl stop tomcatX
  [root@eapps-example ~]# systemctl start tomcatX
  [root@eapps-example ~]# systemctl restart tomcatX

Tomcat Application deployment

Your Virtual Server includes the Apache web server as part of the base environment. Apache is designed to serve static HTML content, perl scripts, PHP applications, and other types of content that requires a web server. Tomcat is designed primarily to serve JSP pages and servlets.

One of the decisions you will need to make when deploying your Tomcat application is how you want Tomcat and Apache to interact. In most cases you will want to use Apache as a front end to Tomcat. In very rare cases you may want to run Tomcat without Apache.

Before you proceed you will need to determine which of the three approaches below is appropriate for you. The three supported approaches for deployment are:

• Using Apache and mod_jk – the most common way of configuring Tomcat and Apache. mod_jk is older and a bit more robust than the newer mod_proxy_ajp. With mod_jk, you specify directives that tell Apache whether to pass the request on to Tomcat, or if Apache will handle the request itself.

• Using Apache and mod_proxy_ajp – similar to using mod_jk, in that you have to specify directives to forward requests from Apache to Tomcat.

• Using Tomcat without Apache – this approach is only used when your Virtual Server does nothing but run a Tomcat application. In other words, it is not used for e-mail, or any other function other than the Tomcat application.

For instructions on how to use each of the three supported approaches, please see the User Guide for that specific approach. Note that mod_jk and mod_proxy_ajp are covered in the same user guide.

• Tomcat Application Deployment with Apache
• Tomcat 7 Application Deployment without Apache

Tomcat Manager

The Tomcat Manager application can be used to deploy WAR files, stop and reload Tomcat applications, and check the status of the Tomcat server. For more information on how to use and configure Tomcat Manager, click on the HTML Manager Help and Manager Help links in the Manager interface.

Enabling Tomcat Manager

Tomcat Manager is enabled on a per-domain basis. This means that you will need to add the Context for the Tomcat Manager application to the Host block in server.xml for each domain where you want to access it.

To enable Tomcat Manager, you will need to edit the server.xml file located in the /opt/tomcatX/conf directory (substitute X for your version of Tomcat). This is done from the command line of the Virtual Server, or from the File Manager of your Control Panel.

Once you have finished editing server.xml, you will need to restart Tomcat.

In server.xml find the Host block where you wish to add Tomcat Manager, and add this Context below the existing one:

When you're done, the entire Host block will look similar to this:

Remember, this is just an example, you will need to use your own domain name and appBase/docBase locations.

Save and exit the file, and then restart Tomcat.

Accessing Tomcat Manager

To access the Tomcat Manager, go to http://eapps-example.com:8080/manager/html or http://IP_ADDRESS:8080/manager/html. Make sure to substitute your own domain name or IP address for eapps-example.com.

You will be asked to log in to Tomcat Manager. The User Name is admin, and the Password is found in /opt/tomcatX/conf/tomcat-users.xml - look at the next to last line in that file.

Changing the Tomcat Manager password

To change the password for Tomcat Manager, edit the tomcat-users.xml file in the /opt/tomcatX/conf directory. The next to last line in the file will have the user name and password:

<user username="admin" password="password" roles="tomcat,manager-gui,manager-status,admin-gui"/>

Set the password to your desired password, and save and exit the file. Restart Tomcat for the changes to take effect.

Tuning Tomcat

Java Heap Settings – an overview

One of the most important parts of tuning Tomcat for better performance is to optimize the Java Heap settings. The Java Heap size is the amount of memory allocated to the Java Virtual Machine (JVM). The heap is where Java objects live, and there must be enough memory allocated to the JVM to support the needs of the deployed Tomcat applications.

The most common issue with Tomcat, by far, is a lack of available resources. In many cases, this is due to the Java Heap size either not being configured at all, or not being configured correctly. In other cases, the Virtual Sever is simply too small for the type of application being run on it. For a small Tomcat application, make sure your VS has at least 768 MB of RAM, and be prepared to scale upwards.

How to find the correct Java Heap Settings for your Virtual Server

By default Tomcat is configured to use a minimum of 64 MB of RAM and a maximum of 128 MB of RAM allocated to the heap. At a minimum, the maximum setting will need to change in order to correctly optimize Tomcat.

To find the correct heap size, you will have to stop Tomcat, and use the Linux free -m command to see the available memory. Then you will need to multiply that value by two, and then subtract that result from the total RAM available for your plan. This number will be roughly what you need to set for the maximum heap size.

All of this must be done from the command line of the Virtual Server, as the root user.

[root@eapps-example ~]# free -m
              total       used       free     shared    buffers     cached
Mem:          1024        285        738          0         13        153
-/+ buffers/cache:        118        905
Swap:         1055          0       1055

In this example, with Tomcat stopped, the Virtual Server and all other applications are using 285 MB of memory.

Multiply this value by two, giving a total of 570 MB. Subtract that from the total amount of memory available to the Virtual Server (1024 MB), for a maximum value of 454 MB for the maximum heap size for the VS.

Remember, this is only an example. Your Virtual Server + applications will produce a different result. You will find that you need to adjust this number up or down as necessary, depending on how your application is configured and what other services your Virtual Server is running.

Generally, the maximum heap size should be just under half the amount of memory available to your VS. You can of course adjust this value higher or lower, but you may have to experiment to determine the true optimum heap size. However, do not set your maximum heap size to a number higher than your Virtual Server actually has available for memory. This will cause problems with Tomcat, including constant crashes.

Adjusting the Java Heap settings

To set the Java Heap for Tomcat you must modify the wrapper.java.initmemory and the wrapper.java.maxmemory settings in the /etc/tomcatX/tomcat.conf file. It is best to set the initmemory parameter lower than the maxmemory parameter to ensure that Java does not initialize more memory than is actually needed. This will optimize memory for non-Java processes.

You can use either the File Manager in your Control Panel to change the Java Heap settings, or connect to the Virtual Server and edit the file from the command line. If you have the ISPmanager Control Panel, more information can be found here - File Manager for ISPmanager 4 or File Manager for ISPmanager 5.

The default values for the Java Heap Size are 64 MB for wrapper.java.initmemory and 128 MB for wrapper.java.maxmemory. Change the value to your desired Java Heap settings, and save and exit the file.

# Initial Java Heap Size (in MB)
wrapper.java.initmemory=64
# Maximum Java Heap Size (in MB)
wrapper.java.maxmemory=128

Once you have made the changes and saved the file, restart Tomcat for the new Java Heap settings to take affect.

Use Database Connection Pooling (DBCP) When Necessary

Database connection pooling can reduce connection creation time and resource usage, especially on sites with a high load. The following steps can help you implement Database Connection Pooling for your application deployed on Tomcat.

Install the correct JDBC driver

If you are using MySQL for you database, you will need to install the MySQL JBDC Driver application. For PostgreSQL, you will need the PostgreSQL JDBC Driver.

Context Configuration

Add the lines below to your context configuration in your Host element in server.xml, in your application META-INF/context.xml, or in your /opt/tomcatX/conf/Catalina/hostname/context.xml. The exact location will depend on how you have deployed your application.

For MySQL:

<Resource name="jdbc/myDB" auth="Container" type="javax.sql.DataSource"
maxActive="100" maxIdle="30" maxWait="10000
username="myuser" password="mypasswd" driverClassName="com.mysql.jdbc.Driver"
url="jdbc:mysql://localhost:3306/javatest?autoReconnect=true"/>

For PostgreSQL:

<Resource name="jdbc/myDB" auth="Container"
type="javax.sql.DataSource" driverClassName="org.postgresql.Driver"
url="jdbc:postgresql://127.0.0.1:5432/javatest"
username="myuser" password="mypasswd" maxActive="20" maxIdle="10"
maxWait="-1"/>

General Notes About the Parameters Used Above (from the apache.org Tomcat Documentation)

• maxActive - Maximum number of dB connections in pool. Make sure you configure your mysqld max_connections large enough to handle all of your db connections. Set to -1 for no limit

• maxIdle - Maximum number of idle dB connections to retain in pool. Set to -1 for no limit. See also the DBCP documentation on this and the minEvictableIdleTimeMillis configuration parameter.

• maxWait - Maximum time to wait for a dB connection to become available in ms, in this example 10 seconds. An Exception is thrown if this timeout is exceeded. Set to -1 to wait indefinitely.

• user name and password - MySQL dB user name and password for dB connections

• driverClassName - We recommend using Connector/J driver. Class name for the official MySQL Connector/J driver is com.mysql.jdbc.Driver

• url - The JDBC connection url for connecting to your MySQL dB. The autoReconnect=true argument to the url makes sure that the mm.mysql JDBC Driver will automatically reconnect if mysqld closes the connection. By default mysqld closes idle connections after 8 hours.

web.xml Configuration

You will also need to configure your application WEB-INF/web.xml file to use the database resource. In your web.xml file add a resource reference like the one below for both MySQL and PostgreSQL.

<resource-ref>
<description>DB Connection</description>
<res-ref-name>jdbc/myDB</res-ref-name>
<res-type>javax.sql.DataSource</res-type>
<res-auth>Container</res-auth>
</resource-ref>