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:

tomcatHome/bin/version.sh

Step 2  Check your configuration

To find out what changes have been made to Tomcat configuration files, compare your configuration files to those in a standard installation, as follows.

1. Using the instructions in Install Tomcat on Linux, download and install your current version of Tomcat in a temporary location, TmpCurrent.
Do not install this temporary installation to /opt/tomcat.

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

   diff /opt/tomcat/conf TmpCurrent/conf

3. 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. see 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.

Step 3  Back-up the current Tomcat installation

1. Stop Tomcat.

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

   sudo systemctl stop tomcat
   sudo mv /opt/tomcat/ /opt/tomcat-back

Step 4  Install the new version of Tomcat

1. To install the required new version of Tomcat, follow the instructions on Install Tomcat on Linux.

Step 5  Configure the new version of Tomcat

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

   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.

   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 continue to work after the upgrade.

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

   • also updated Java

   • installed Tomcat in the same location as previously check

   
   

Step 6  Restart and Test

1. Restart Tomcat

   sudo systemctl start tomcat

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

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

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

   /opt/tomcat/bin/version.sh

On Windows

The following instructions assume that Tomcat is installed in the tomcat base directory, as recommended in PhixFlow’s installation instructions. 

Step 1 Identify your current version of Tomcat

In PowerShell, check the version

$tomcat\bin\version.bat

Step 2 Check your configuration

To find out what changes have been made to Tomcat configuration files, compare your configuration files to those in a standard installation, as follows.

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

2. Unpack it to a temporary directory, for example TempCurrent. Do not install it.

   
   

3. Use the compare command to find the differences between the TmpCurrent/conf files and those in your current installation's conf directory. For example, in PowerShell, enter:

   compare-object (get-content $tomcat\conf\file.xml) (get-content $standardInstallCurrentVersion\conf\file.xml)

4. Compare the following files in TmpCurrent/conf directory with those in your current installation's conf directory, for example:

   • 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. see below.

Step 3 Back-up the current Tomcat installation

1. Copy the entire tomcat 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 tomcat/ 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 system's Java setup.
   
   
   In particular, note:
   • the path of the Java Virtual Machine

   • Java options. PhixFlow recommends:

     
     

     -Djava.awt.headless=true
     -XX:+PrintGCDetails
     -XX:+PrintGCDateStamps
     -Xloggc:C:\tomcat\logs\gc-%t.log

   • 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 available. 

Step 4 Uninstall the current version of Tomcat

1. Open Add or remove programs.
   
2. Locate Tomcat and click Uninstall. 
3. Windows asks if you want to remove all files:
   
   
   
   • Click Yes if you have taken a backup of the necessary folders in Step 3. 
   • 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 4 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:

• recommended for PhixFlow; see Configure the service wrapper

• you noted in Step 4, such as:

  • JVM path

  • memory settings

  • service account; see Run under service account.

Step 5 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 tomcat\webapps\phixflow

2. If you have custom folders, copy 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 (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.

Step 6 Restart and Test

1. Restart Tomcat

   sudo systemctl start tomcat

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

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

3. Check that you are now running the required version of Tomcat. In PowerShell, enter:

   tomcat\bin\version.bat