Versions Compared

Key

  • This line was added.
  • This line was removed.
  • Formatting was changed.

This page is for system administrators who are upgrading Tomcat.

Overview

The instructions on this page provide guidance on how to upgrade:

  • a standard Tomcat setup 
  • a Tomcat setup with some configuration changes to server.xml and web.xml

Most PhixFlow installations use a standard Tomcat setup. Some common variations are:

  • SSL termination is handled in Tomcat to provide a secure connection. This means you have installed a certificate.

  • Tomcat uses a non-standard port number.

  • PhixFlow can export large files because the limit set by maxPostSize has been increased or disabled; see Configuring Large Image Upload.

To upgrade, we recommend you install the target version of Tomcat as a new installation, then move resources and configuration changes from the previous install. This means the common variations listed above will be moved into the new installation.

Tomcat provides a tool for comparing configuration files between patch versions; for example, for version 9 see https://tomcat.apache.org/migration-9.html#Upgrading_9.0.x. However, at PhixFlow, we have found it easier and more reliable to treat even minor upgrades as new installations.


Panel
borderColor#7da054
titleColorwhite
titleBGColor#7da054
borderStylesolid
titleSections on this page

Table of Contents
maxLevel3
indent12px
stylenone


On Linux

The following instructions assume that Tomcat is installed in /opt/tomcat, as recommended in PhixFlow’s installation instructions. If you have installed Tomcat somewhere else, remember to replace /opt/tomcat in commands with your installation directory. 

Step 1  Identify your current version of Tomcat

At the command line, enter:

Code Block
/opt/tomcat/bin/version.sh

Step 2  Check your configuration (if necessary)

You can skip this step if you have:

  • made no configuration changes to Tomcat
  • notes or a checklist of your configuration.

If you have made configuration changes but cannot remember what they are, you can find out by comparing your current configuration files to those in a standard installation.

  1. Find your current version of Tomcat on the Tomcat download page:
  2. Download your current version to a temporary location, for example /tmp/tmpTomcat, and unpack it:

    Code Block
    cd /tmp
    mkdir tmpTomcat
    cd tmpTomcat
    curl -O https://archive.apache.org/dist/tomcat/tomcat-8/v8.0.45/bin/apache-tomcat-8.0.45.tar.gz
    tar xvf apache-tomcat-8*tar.gz --strip-components=1


  3. Use the diff command to compare the conf directory with your current installation's conf directory, for example:

    Code Block
    diff /opt/tomcat/conf /tmp/tmpTomcat/conf


  4. Make a note of any differences between the two configurations.
    You will need to reproduce these changes in the new installation in Step 5, below.
    In particular, check for changes in:
    • server.xml
    • context.xml
    • web.xml
    • tomcat-users.xml.
      PhixFlow does not recommend updates to this file but you may have enabled internal Tomcat users.
  5. Remove your temporary download. For example:

    Code Block
    cd /tmp
    rm -r tmpTomcat


Step 3  Back-up the current Tomcat installation

  1. Stop Tomcat.
    If you have installed Tomcat to run under systemd, enter: 

    Code Block
    sudo systemctl stop tomcat


  2. Move the current /opt/tomcat directory into a backup.

    Code Block
    sudo mv /opt/tomcat/ /opt/tomcat-back


Step 4  Install the new version of Tomcat

To install the required new version of Tomcat:

Insert excerpt
Install Tomcat on Linux
Install Tomcat on Linux
nopaneltrue

Step 5  Configure the new version of Tomcat

  1. Move the PhixFlow webapp from the backup into the new Tomcat webapps directory.

    Code Block
    sudo mv /opt/tomcat-back/webapps/phixflow /opt/tomcat/webapps/


  2. If you have custom folders, move them back into the new Tomcat installation, for example tomcat/secure and tomcat/metadata.

  3. Apply the standard configuration settings and hardening steps; see Install Tomcat.

  4. Copy your specific configurations from the backup files into the Tomcat configuration files, for example: SSL termination, non-standard ports, etc.
    Copy only the sections that are specific to your installation.

    Tip

    You do not need to re-create the service configuration for Tomcat. For example, if you previously installed Tomcat to run under systemd, the service script will continue to work after the upgrade.

    You may need to revise your service configuration if you have:

    • also updated Java

    • not installed Tomcat in the same location as previously.


Step 6  Restart and Test

  1. Restart Tomcat

    Code Block
    sudo systemctl start tomcat


  2. Test that Tomcat is running and the PhixFlow webapp can run:

    Code Block
    sudo systemctl status tomcat
    curl http://localhost:8080/phixflow/start.html

  3. Check that you are now running the required version of Tomcat:

    Code Block
    /opt/tomcat/bin/version.sh


On Windows

The following instructions assume that you already have Tomcat 9 installed in c:\app\tomcat9as recommended in PhixFlow’s installation instructions. If Tomcat is at a different version, and/or you have chosen to install it in a different location, remember to replace c:\app\tomcat9 in the following commands with your installation directory.

Step 1 Identify your current version of Tomcat

To run the following process you must have the following environment variables set:

  • CATALINA_HOME
  • and either JAVA_HOME or JRE_HOME.

If you have not set these variables, you can set them in your current session. For example, in Powershell, enter:

Code Block
$env:JAVA_HOME="C:\Program Files\Java\jre1.8.0_282"
$env:CATALINA_HOME="C:\app\tomcat9"

To check the version, in PowerShell enter:

Code Block
& "C:\app\tomcat9\bin\version.bat"

Step 2 Check your configuration

You can skip this step if you have:

  • made no configuration changes to Tomcat
  • notes or a checklist of your configuration.

If you have made configuration changes but cannot remember what they are, you can compare your configuration files to those in a standard installation.

  1. Download a new copy of your current version of Tomcat.

  2. Find your current version of tomcat on the Tomcat download page:
  3. Download your current version and unpack it to a temporary directory, for example TempCurrent. Do not install it.
  4. Use the compare command to find the differences between the TempCurrent\conf files and those in your current installation's conf directory. For example, in PowerShell, enter:

    Code Block
    compare-object (get-content c:\app\tomcat9\conf\file.xml) (get-content TempCurrent\conf\file.xml)

    In particular, you are looking for differences in the following files:

    • server.xml
    • context.xml
    • web.xml
    • tomcat-users.xml.
      PhixFlow does not recommend updates to this file but you may have enabled internal Tomcat users.
  5. Make a note of any differences between your current installation and the test installation.
    You will need to reproduce these changes in the new installation in Step 5 below.
  6. Remove your temporary download.

Step 3 Back up the current Tomcat installation

  1. Copy the entire tomcat9 folder to a backup location.

  2. If your log files are large and you do not want to retain them, as a minimum, you must back up the following tomcat9\ sub-folders:

    • webapps

    • conf

    • lib

    • bin

    • and if they exist: metadata and secure.

Step 4  Note your Java setup

  1. Check and make a note of your changes to the Java setup, including those required by PhixFlow. 


    In particular, note:
    • the path of the Java Virtual Machine
    • Java options. Make a note of any options you have added in addition to the PhixFlow recommendations. PhixFlow recommends:

      Insert excerpt
      Install Tomcat on Windows
      Install Tomcat on Windows
      nopaneltrue

    • Memory allocation
  2. On the server, open Services → Apache Tomcat service properties:


If Tomcat is running under a service account, make a note of the service account name. Ensure you have the service account password. 

Step 5 Uninstall the current version of Tomcat

Note

We do not recommend using Uninstall.exe in the tomcat9 base directory as we found it did not work. The following method above has proved more reliable.

  1. Open Add or remove programs.
  2. Locate Tomcat and click Uninstall
  3. Windows asks if you want to remove all files:


    • Recommended - Click Yes if you have taken a backup of the necessary folders in Step 3.
    • Alternatively - Click No if you want Windows to keep the conf, logs, null and webapps directories, as well as any other directories you have added.

Step 6 Install the new version of Tomcat

To install the required new version of Tomcat, follow the instructions on Install Tomcat on Windows. Remember to reapply the settings:

Step 7 Configure the new version of Tomcat

  1. Copy the PhixFlow webapp from the backup into the new Tomcat webapps directory, for example from backup\webapps\phixflow to tomcat9\webapps\phixflow.

  2. If you have custom folders, copy them back into the new Tomcat installation, for example tomcat9\secure and tomcat9\metadata.

  3. Apply the standard configuration settings and hardening steps; see Install Tomcat.

  4. Copy your specific configurations (as identified in Step 2) from the backup files into the Tomcat configuration files, for example: SSL termination, non-standard ports, etc.
    Copy only the sections that are specific to your installation.

  5. If you are using MS SQL Server integrated authentication, make sure you have replaced the Java option to set the classpath for sqljdbc_auth.dll. This should be included in the additional Java options you captured above, but to be certain, you can check instructions for Tomcat configuration on MS SQL Server Integrated Authentication (you do not need to reapply updates to the phixflow-datasource.xml, because this is included in the PhixFlow webapp you have already copied back into the new Tomcat installation)

Step 8 Restart and Test

  1. Restart the Tomcat service and check that it is running.

  2. Start the PhixFlow webapp and check that it is running.

  3. Check that you are now running the required version of Tomcat.
    Assuming you have set the JAVA_HOME or JRE_HOME environment variable, in PowerShell, enter:

    Code Block
    & "C:\app\tomcat9\bin\version.bat"