On Linux

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

Step

1  Identify your current version of Tomcat

At the command line, enterLenter:

tomcatHome/bin/version.sh

Step

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.

The following instructions will upgrade a standard Tomcat setup, or a setup with any of the variations listed above,  if you re-apply your configuration changes to server.xml and web.xml.

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

1. 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; see , 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

Below, $tomcat refers to the Tomcat base directory.

PreparationThe 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

Most PhixFlow installations use a fairly standard setup in tomcat, but there are some possible variations. Commonly, these are:

You handle SSL termination in tomcat to provide a secure connection, i.e. you have installed a certificate

You use a non-standard port number

You have allowed large files to be exported from PhixFlow by increasing the limit allowed by maxPostSize

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. To do so, download , as follows.

1. Download a new copy of your current version of

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

1. • . PhixFlow does not

1. • recommend updates to this file

1. • but you may have enabled internal

1. • Tomcat users

using the command compare-object (get-content $tomcat\conf\file.xml) (get-content $standardInstallCurrentVersion\conf\file.xml) in PowerShell.

Upgrade

Stop Tomcat

1. • .

   
   

2. 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,

1. you must back up the following tomcat/ sub-folders:

1. • webapps

1. • conf

1. • lib

1. • bin

$tomcat\metadata, if this exists

$tomcat\secure, if this exists

1. • 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:

1. the path of the Java Virtual Machine

2. Java options

1. 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 )

2. Memory allocation
3. If tomcat is running under a service account, take account of the service account name, and make sure that you have the service account password available. To see this, open services on the server and open the properties for the Apache Tomcat service:
   Image Added

Step 4 Uninstall the current version of Tomcat

We do not recommend using Uninstall.exe in the tomcat 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'. The below question will pop up. Since we backed up

1. Uninstall. 
2. Windows prompts you to
   
   If you have taken a backup of the necessary folders in

step

1. Step 3,

you can

1. click yes

(if you click no, it will keep

1.  
   Alternatively, click no so that Windows keeps the conf, logs, null and webapps directories, as well as any other directories you have added

)We have tried using Uninstall

1. .

exe in $tomcat, but this did not work. The method above has proved more reliable.

The following instructions reference several sections of the page https://phixflow.atlassian.net/wiki/spaces/HELPTRUNKR/pages/304087050/Install+Tomcat+on+Windows :

Section Download and install Tomcat: Download and install the latest version of Tomcat

Section Configure the service wrapper: re-apply the settings (Java options) as

Step 4 Install the new version of Tomcat

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

2. Remember to re-apply the your Java optionsas recommended on that page, and settings you captured above for the Java configuration (JVM path, memory settings, any Java options you applied in addition to the standard setup) Configure the service wrapper

1. Section Run under service account

1.  if you identified above that tomcat was being run under a service account re-apply this configuration

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

   
   

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

$tomcat\bin\version.bat