Skip to main content

IMPORTANT - Product End of Life Statement - IMPORTANT

Request RE, Survey, and Calendar 1.5 Support Ending December 31, 2020
Contact Kinetic Data Support with Questions
Kinetic Community

Installing Multiple Tomcat Servers on Linux


This guide shows how to install multiple Tomcat servers on the same Linux server, or more specifically, the same Debian / Ubuntu Linux server.


While it may be a fairly straightforward approach to install multiple Tomcat servers on the same server by simply making a copy of an existing Tomcat directory, this makes it difficult to upgrade the Tomcat server or apply security patches.

A better approach is to separate the tomcat home and base directories.  This allows for all the configuration files and web application to be placed in the Tomcat base directory, and leave the scripts and libraries in the Tomcat home directory.  Applying upgrades is as easy as downloading the new Tomcat server and sym-linking the new home directory.

Catalina Home

The home directory contains all the Tomcat scripts and libraries that make up the Tomcat server.  A single catalina home installation can used to run multiple catalina base instances.

The easiest way to think of the catalina home directory is to just download the Tomcat binary distribution package (either .zip or .tar.gz), and extract it to a directory.  The extracted directory is the catalina home directory.

With a symbolic link called tomcat-home that is pointed to the extracted distribution directory, it is very easy to upgrade the Tomcat server version if necessary by simply changing the symbolic link to point to the desired Tomcat distribution.

Catalina Base

The base directory represents the location of the Tomcat configuration files, deployed web applications, log files, temporary files directory, etc... The attached file is basically the structure that can be used to represent this CATALINA_BASE directory.  When installing multiple Tomcat servers, what you are really doing is installing multiple catalina base directories.

In this skeleton, the Tomcat Manager and Root web applications are automatically linked to the applications in the tomcat-home directory.  If you need to override or remove these, please see the webapps/README.txt file for instructions on how to do that.

The Tomcat Manager application is restricted to a single user, defined in the conf/tomcat-users.xml file.

Linux systemd initialization script

Within the catalina base skeleton directory is the systemd initialization script that contains all the configuration data that will be passed on to the Tomcat server when it is started.  This is where you set the ports the Tomcat instance should use to listen to serve HTTP and/or HTTPS requests, and to shutdown the server.  This is also where you indicate the location of the CATALINA_BASE directory, CATALINA_HOME directory, and the JAVA_HOME directory.  This file needs to be moved or copied to the /etc/init.d/ directory so it can be configured to start the Tomcat server when the Linux server is started.


The resulting directory structure keeps all the tomcat servers and distributions together making them easy to find.

        |- dist/
                |- apache-tomcat-8.0.29/
                |- apache-tomcat-8.0.33/
                |- apache-tomcat-8.0.35/
                |- tomcat-home -> /opt/tomcat/dist/apache-tomcat-8.0.35
        |- tomcat-bridgehub/
        |- tomcat-calendar/
        |- tomcat-filehub/
        |- tomcat-request-ce/
        |- tomcat-schedule/
        |- tomcat-task/

Using systemd as the initialization system instead of upstart allows working with the Tomcat services via the following syntax, which is consistent with other flavors of Linux.

service <servicename> start|stop|status|restart|reload

Using systemd also keeps all of the service scripts in the /etc/init.d directory, also consistent with other flavors of Linux.

        |- ...
        |- tomcat-task
        |- tomcat-placeholder
        |- ...

Example - Installing Multiple Tomcat Servers

This example will show how to install two Tomcat servers running from a single Catalina Home deployment.  It will also show how to upgrade the Tomcat distribution to a newer version after it was originally installed.

  1. Create a tomcat user that will be used to run the Tomcat servers
  2. sudo adduser --system \
            --home /opt/tomcat \
            --group \
            --disabled-password \
            --disabled-login \
            --gecos "Apache Tomcat web server,,," \
  • This command creates a Linux user named tomcat that can be used to run the Tomcat servers instead of the root user.
  • It sets the account as a system user.
  • It indicates what the home directory for the user will be, and creates the directory if it doesn't exist.
  • It also creates a group with the same name - tomcat.
  • It explicitly disables the password for this user.
  • It explicitly disables login for this user.
  • It sets a description of what the user account is for.
  1. OPTIONAL - Add the ubuntu user to the tomcat group
  2. sudo usermod -a -G tomcat ubuntu
  • This adds the ubuntu user to the tomcat group and gives the ubuntu user the ability to modify files created by the tomcat user
  • You may skip this step if it doesn't apply to your environment
  1. Install the Tomcat Distribution and symlink as tomcat-home
  2. export TOMCAT_VER=8.0.33
    sudo -u tomcat mkdir -p /opt/tomcat/dist && cd /opt/tomcat/dist
    sudo -u tomcat curl -L \
    sudo -u tomcat tar xzf apache-tomcat-$TOMCAT_VER.tar.gz && sudo -u tomcat rm apache-tomcat-$TOMCAT_VER.tar.gz
    sudo ln -s /opt/tomcat/dist/apache-tomcat-$TOMCAT_VER /opt/tomcat/dist/tomcat-home
  • Line 1 defines the version of the Tomcat distribution to download
  • Line 2 creates the /opt/tomcat directory if it doesn't exist, then creates the /opt/tomcat/dist directory if it doesn't exist, and finally changes directory to /opt/tomcat/dist
  • Line 3 downloads the tomcat distribution via the curl command to the current directory, follows any temporary redirects by the server, and preserves the original file name
  • Line 4 unpacks the distribution file and removes the compressed archive
  • Line 5 creates a symbolic link from the tomcat-home directory used by the tomcat servers, to the currently downloaded distribution
  1. Update the file permissions for the tomcat user and group
sudo chown -R tomcat:tomcat /opt/tomcat
  • Changes permissions to allow the tomcat user to own all files within the /opt/tomcat directory 
  1. Add an access control list to the tomcat directory so the tomcat group is always applied to files and directories
sudo chmod -R 775 /opt/tomcat
sudo chmod -R g+s /opt/tomcat
sudo setfacl -Rdm g:tomcat:rwx /opt/tomcat
  • Line 1 gives recursive read/write/execute access to the user that created the file and group, and read/execute access to everyone else
  • Line 2 adds the sticky bit recursively to group access
  • LIne 3 sets a file access control list that recursively applies the tomcat group with read / write / execute access to all files and sub-directories.  This step requires the acl package is installed on the server.
  1. Download the Catalina base skeleton file structure
cd /opt/tomcat
sudo -u tomcat curl -L -O
sudo -u tomcat unzip
  • Change location to the /opt/tomcat directory
  • Download the catalina base skeleton from Kinetic Community using the curl utility
  • Unzip the archive package.  This step requires the unzip package is installed on the server.
  1. Install a Catalina Base Directory
sudo -u tomcat cp -R catalina-base-skeleton tomcat-<placeholder>

# If this Tomcat server was specifically for Kinetic Task - a good name would be tomcat-task
# mv catalina-base-skeleton tomcat-task
  • Copies the extracted skeleton directory to a new directory to reflect the purpose of this Tomcat server
  • You must replace the <placeholder> portion with your value.
  • The replacement should not have any spaces or special characters.  Try to stick with alpha-numeric and hyphens.
  1. Update the permissions on the directory
sudo -u tomcat chmod -R 774 /opt/tomcat/tomcat-<placeholder>

# If using the value tomcat-task from the previous step
# sudo chmod -R 774 /opt/tomcat/tomcat-task

  • This script excerpt changes file access recursively to allow the current user and any user of the tomcat group access to the tomcat directory 
  1. Update the systemd script
  • Edit the tomcat-<placeholder>/tomcat-placeholder file with a text editor (nano, vi, emacs, etc...)
sudo -u tomcat vi tomcat-<placeholder>/tomcat-placeholder

# If using the value tomcat-task from the previous step
# vi tomcat-task/tomcat-placeholder
  • The main properties that you need to inspect are on lines 19-33, with the main properties between lines 19-27.  There are some additional properties that may need to be modified if the tomcat server is running behind a proxy server, or if SSL is required to be handled by the Tomcat server.
#! /bin/sh
# Provides:          tomcat
# Required-Start:    $remote_fs $syslog
# Required-Stop:     $remote_fs $syslog
# Default-Start:     2 3 4 5
# Default-Stop:      0 1 6
# Short-Description: Tomcat web server
# Description:       Tomcat web server for Kinetic applications.
# Author: Kinetic Data <>

# Add to systemd
# sudo update-rc.d tomcat-task start 70 2 3 4 5 . stop 30 0 1 6 .

# If using a proxy server, add the proxyPort and proxyName configuration values
# to the connector in the conf/server.xml file

export CATALINA_BASE=/opt/tomcat/$NAME
export CATALINA_HOME=/opt/tomcat/dist/tomcat-home
export $JAVA_HOME

  1. Move the systemd script to the /etc/init.d/ directory and set ownership and permissions
sudo mv tomcat-<placeholder>/tomcat-placeholder /etc/init.d/tomcat-<placeholder>
sudo chown root:root /etc/init.d/tomcat-<placeholder> && sudo chmod +x /etc/init.d/tomcat-<placeholder>

# If using the value tomcat-task from the previous step
# sudo mv tomcat-task/tomcat-placeholder /etc/init.d/tomcat-task
# sudo chown root:root /etc/init.d/tomcat-task && sudo chmod +x /etc/init.d/tomcat-task

  • This simply copies the file to the systemd services directory, and then sets permissions on the file 
  1. Add to systemd and start the service 
sudo update-rc.d tomcat-<placeholder> start 70 2 3 4 5 . stop 30 0 1 6 .
sudo service tomcat-<placeholder> start

# If using the value tomcat-task from the previous step
# sudo update-rc.d tomcat-task start 70 2 3 4 5 . stop 30 0 1 6 .
# sudo service tomcat-task start 
  • This indicates what run levels the service should start and stop, and then starts the service 
  1. Repeat steps 7-11 for each Tomcat instance that needs to be installed.
  2. Enjoy

Example - Upgrading the Tomcat Distribution

When you need to update the Tomcat distribution due to a bug in a previous version, or a security fix.  Here is the procedure to do that.

  1. Stop all Tomcat instances
sudo service tomcat-<placeholder> stop
  1. Install new Tomcat distribution
export TOMCAT_VER=8.0.35
cd /opt/tomcat/dist/
curl -L -O$TOMCAT_VER/bin/apache-tomcat-$TOMCAT_VER.tar.gz
tar xzf apache-tomcat-$TOMCAT_VER.tar.gz && rm apache-tomcat-$TOMCAT_VER.tar.gz

  1. Update tomcat-home symbolic link
sudo rm /opt/tomcat/dist/tomcat-home
sudo ln -s /opt/tomcat/dist/apache-tomcat-$TOMCAT_VER /opt/tomcat/dist/tomcat-home
  1. Start Tomcat instances
sudo service tomcat-<placeholder> start