Linux

The following instructions assume that tomcat is installed in /opt/tomcat, as recommended in PhixFlow’s installation guide for tomcat. But if you have installed it elsewhere, replace /opt/tomcat with this installation directory.

Step 1 Check your current version of Tomcat

At the command line, enterL

tomcatHome/bin/version.sh

Step 2 Check your Setup

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.

Linux Upgrade Steps

1. Stop Tomcat.

2. Move the current /opt/tomcat directory to create a backup

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

3. Follow the standard instructions for installing tomcat at Install Tomcat on Linux

4. Move the PhixFlow webapp back in

   sudo mv /opt/tomcat-back/webapps/phixflow /opt/tomcat/webapps/

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

6. Apply standard configuration settings and hardening steps, as instructed in Install Tomcat 

7. Remember to make and additional configuration changes if your Tomcat is different from 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

   It is not necessary to re-create the service configuration for tomcat providing that:

   1. You have not updated Java at the same time

   2. You have installed tomcat at the same location as previously

   For example, if you previously installed tomcat to run under systemd, the service script will be unaffected by the tomcat upgrade.

   
   

8. Restart tomcat

   sudo systemctl start tomcat

9. Check that tomcat is running ok & the webapp is up

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

10. Check version

    /opt/tomcat/bin/version.sh

Windows

Below, $tomcat refers to the Tomcat base directory.

Preparation

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

All of the above are already covered in the steps below, by re-applying changes to server.xml and web.xml. However, if in doubt, you could check by comparing your configuration files to those in a standard installation. To do so, download your current version of tomcat, unpack it, but do not install it - just place it in $standardInstallCurrentVersion

Then compare the following files

server.xml

context.xml

web.xml

tomcat-users.xml (PhixFlow does not mandate or even recommend updates to this file; but you may have enabled internal tomcat users)

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

Upgrade

Stop Tomcat

Backup the current tomcat folder; e.g. copy the entire $tomcat folder to a backup location. If your log files are large and you do not want to retain them, as a minimum, make sure you back up the following sub-folders:

$tomcat\webapps

$tomcat\conf

$tomcat\lib

$tomcat\bin

$tomcat\metadata, if this exists

$tomcat\secure, if this exists

Make a note of the Java setup, including:

Path of the Java Virtual Machine

Java options applied in addition to the standard setup (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

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:

Uninstall Tomcat. To do this, open ‘Add or remove programs’

Locate Tomcat and click ‘Uninstall'. The below question will pop up. Since we backed up the necessary folders in step 3, you can click yes (if you click no, it will keep the conf, logs, null and webapps directories, as well as any you have added)

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

Section Run under service account: if you identified above that tomcat was being run under a service account re-apply this configuration

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