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:

   Code Block
   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  Move the current Tomcat installation into a backup

1. Stop Tomcat.

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

   Code Block
   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.

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

   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 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:

   Code Block
   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, including.
   
   Image Added
   In particular, note:
   • the path of the Java Virtual Machine

   • Java options

   Tip

   • . PhixFlow recommends:

     Insert excerpt
     Install Tomcat on Windows Install Tomcat on Windows nopanel true

   remember that PhixFlow recommends some options, see Java Options on https://phixflow.atlassian.net/wiki/spaces/HELPTRUNKR/pages/304087050/Install+Tomcat+on+Windows )Memory allocation

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

Image Added
If tomcat is running under a service account,

make a note of the service account name

. Ensure you have the service account password available.

Image Removed

Step 4 Uninstall the current version of Tomcat

1. Open Add or remove programs.
   Image Added
2. Locate Tomcat and click Uninstall. 
3. Windows prompts asks if you want to
   If remove all files:
   Image Added
   
   
   • Click Yes if you have taken a backup of the necessary folders in Step 3
   , click yes 
   Alternatively, click no so that Windows keeps
   • . 
   • 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. Move Copy the PhixFlow webapp from the backup into the new Tomcat webapps directory.

   Code Blocksudo mv /opt/tomcat-back/webapps/phixflow /opt/tomcat/webapps/

   , for example from backup\webapps\phixflow to tomcat\webapps\phixflow

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

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

   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. In PowerShell, enter:

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

Copy the webapp back in from backup, e.g. $backup\webapps\phixflow to $tomcat\webapps\phixflow

Copy any other custom folders back in, e.g. $tomcat\secure and $tomcat\metadata

Apply standard configuration settings and harderning steps, as instructed in https://phixflow.atlassian.net/wiki/spaces/HELPTRUNKR/pages/97734713/Install%2BTomcat , ensuring that:

You apply any variation from the standard setup you captured above, including settings for SSL termination, non-standard ports, etc.

You may find it easier to copy the relevant sections from the backup files, but make sure you only copy the sections that needs updating

Start Tomcat and check that PhixFlow is up and running

In PowerShell, check the version

1. \bin\version.bat