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:

/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:
   • for version 8: http://tomcat.apache.org/download-80.cgi
   • for version 9: https://tomcat.apache.org/download-90.cgi
   • for older versions of Tomcat look for your version under Archives → <your version> → bin. Download the link with the format apache-tomcat-VERSION.tar.gz
     

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:

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\tomcat9, as 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:

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

To check the version, in PowerShell enter:

& "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:
   • for version 8: http://tomcat.apache.org/download-80.cgi
   • for version 9: https://tomcat.apache.org/download-90.cgi
   • for older versions of Tomcat look for your version under Archives → <your version> → bin. Download the link with the format apache-tomcat-VERSION-windows-x64.zip
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 nopanel true

   • 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

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:

• 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 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"