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 notes or a checklist of your configuration.

If you cannot remember what configuration changes you have made to Tomcat, 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:

   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:

   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. Make a note of any extra files in your current installation's tomcat/bin  directory. For example, you may have files to integrate with a monitoring agent. Use the diff command to compare the tomcat/bin directory with your current installation's tomcat/bin directory, for example:

   diff /opt/tomcat/bin /tmp/tmpTomcat/bin

   You will copy these files into the new bin directory in step 5.

6. Make a note of any extra files in your current installation's tomcat/lib directory. For example, you may have files to support connections to additional databases. Use diff to compare these directories, for example:

   diff /opt/tomcat/lib /tmp/tmpTomcat/lib

   You will copy these files into the new tomcat/lib directory in step 5

   For connections to databases in addition to Oracle, MySQL and MariaDB, use Database Driver to configure the additional library files required.

7. Remove your temporary download. For example:

   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: 

   sudo systemctl stop tomcat

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

   1. If you have a tomcat-back directory from a previous upgrade, delete it:

      sudo rm -r /opt/tomcat-back

   2. Create the backup:

      sudo mv /opt/tomcat/ /opt/tomcat-back

Step 4  Install the new version of Tomcat

To install the required new version of Tomcat:

1. Download

   1. To find the latest version, go to the Tomcat downloads page: https://tomcat.apache.org/download-90.cgi
   2. Find the latest Binary Distributions section, then the Core sub-heading, and copy the tar.gz link.

   3. To download Tomcat, on the Linux server, go to the tmp directory. Use the curl command to download from the the tar.gz link.

      cd /tmp
      curl -O http://mirror.ox.ac.uk/sites/rsync.apache.org/tomcat/tomcat-9/v9.0.38/bin/apache-tomcat-9.0.38.tar.gz

2. Install

   1. Unpack the Tomcat tar.gz file into /opt/tomcat.

      sudo mkdir /opt/tomcat
      cd /opt/tomcat
      sudo tar xvf /tmp/apache-tomcat-9*tar.gz --strip-components=1

      This creates the tomcat folders (conf, logs, webapps etc.) directly under /opt/tomcat.

   2. Set the file ownership and permissions.

      cd /opt/tomcat
      sudo chown -R tomcat webapps/ work/ temp/ logs/
      sudo chgrp -R tomcat .
      sudo chmod -R g+r conf
      sudo chmod g+x conf

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. If there were any additional files in tomcat/bin, copy these back into the new installation.
4. If there were any additional files in tomcat/lib, copy these  back into the new installation.

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

6. 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 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

   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 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
• JAVA_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 notes or a checklist of your configuration.

If you cannot remember what configuration changes you have made to Tomcat, 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:

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

6. There may be additional files in your current installation's tomcat\bin directory, for example to integrate with a monitoring agent. Use the compare command to compare the bin directory with your current installation's tomcat\bin directory, for example:

   compare-object (get-childitem 'c:\app\tomcat9\bin') (get-childitem 'TempCurrent\bin')

7. Make a note of any extra files in current installation's bin directory - these will need copying back in step 7

8. There may be additional files in your current installation's lib directory - usually these will be for supporting to connections to databases outside of the standard set. Use the compare command to compare these directories, for example:

   compare-object (get-childitem 'c:\app\tomcat9\lib') (get-childitem 'TempCurrent\lib')

   To support connections to databases outside of the standard set, there is now a better way of setting up the additional library files: Database Driver

9. Make a note of any extra files in your current installation's lib directory - these will need copying back in step 7
10. 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. Open Tomcat Properties. If you need further details on how to do this, see: Tomcat start/ stop, open properties
2. Go to the Java tab.
3. 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:

     
     

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

   • Memory allocation
4. 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.
   This step means PhixFlow configuration files, such as phixflow-datasource.xml are updated with your configuration.
   

   1. If the webapp has a datalink, this will need recreating

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

3. If there were any additional files in tomcat9\bin, copy these back into the new installation
4. If there were any additional files in tomcat9\lib, copy these back into the new installation

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

6. 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.

7. If you are using MS SQL Server integrated authentication, remember to replace the Java option to set the classpath for sqljdbc_auth.dll. This should be included in the Java options you noted in Step 4, above. To be certain, you can check instructions for Tomcat configuration on MS SQL Server Integrated Authentication.

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 environment variable, in PowerShell, enter:

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