Linux Before you start

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:

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

Step

2  Check your

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 allowed by maxPostSize has been increased.

The standard Tomcat setup and the above variations are covered by the following instructions, by re-applying changes to server.xml and web.xml.

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, as follows.

1. Install Find your current version of Tomcat in a temporary location, $standardInstallCurrentVersion
   

   Expand
   To find out your current version of Tomcat: $tomcatHome/bin/version.sh Insructions on how to Download and install Tomcat on Install Tomcat on Linux

   Use diff to compare the conf directories in your current installation and the test installation. diff /opt/tomcat/conf $standardInstallCurrentVersionTomcat 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-9/v9.0.95/bin/apache-tomcat-9.0.95-deployer.tar.gz tar xvf apache-tomcat-9*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 your current installation and the test installation. You the two configurations.
   You will need to reproduce these changes after the upgradein 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.

Linux Upgrade Steps

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.

1. Stop Tomcat.

   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:

   Code Block
   diff /opt/tomcat/bin /tmp/tmpTomcat/bin

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

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

   Code Block
   diff /opt/tomcat/lib /tmp/tmpTomcat/lib

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

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

   
   

3. 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 to create into a backup.

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

      Code Block
      sudo

   systemctl

   1. rm

   stop

   1. -r

   tomcat

   1. /opt/tomcat-back

      
      

   2. Create the backup:

      Code Block
      sudo mv /opt/tomcat/ /opt/tomcat-back

   Follow the standard instructions for installing tomcat at 

   1. 
      

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 back infrom the backup into the new Tomcat webapps directory.

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

   
   

2. Copy any other If you have custom folders back in, e.g. $tomcat\secure and $tomcat\metadataApply , 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, as instructed in ; see Install Tomcat 

   Remember to make and additional configuration changes if your Tomcat is different from from the standard setup you captured above, including settings for

   .

6. It is not necessary

   Copy your specific configurations from the backup files into the Tomcat configuration files, for example: 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

   Tip

   
   Copy only the sections that are specific to your installation.

   Tip
   You do not need to re-create the service configuration for tomcat providing that: You have not updated Java at the same time You have installed tomcat at the same location as previously Tomcat. For example, if you previously installed tomcat Tomcat to run under systemd, the service script will be unaffected by the tomcat upgrade.

   Restart tomcat

   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. Check Test that tomcat Tomcat is running ok & and the webapp is upPhixFlow 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

Windows

Below, $tomcat refers to the Tomcat base directory.

Preparation

In PowerShell, check the version

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

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

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. To do so, download your current version of tomcat, unpack it, but do not install it - just place it in $standardInstallCurrentVersionThen compare the following files

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

1. • .
     PhixFlow does not

1. • recommend updates to this file

1. • but you may have enabled internal

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

Upgrade

Stop Tomcat

1. • Tomcat users.
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 in Step 7 below.

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

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

   
   

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

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

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

   
   

   Note
   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

   
   

6. Make a note of any extra files in your current installation's lib directory - these will need copying back in step 7
7. 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,

1. you must back up the following tomcat9\ 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. Open Tomcat Properties. If you need further details on how to do this, see:  Managing Tomcat
2. Go to the Java tab.
3. Check and make a note of your changes to the Java setup, including those required by PhixFlow. 
   
   Image Added
   In particular, note:

1. • the path of the Java Virtual Machine

   • Java options

1. • . Make a note of any options you have added in addition to the

Memory allocation

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

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

. 

Step 5 Uninstall the current version of Tomcat

1. Open Add or remove programs.
   Image Added
2. Locate Tomcat and click

1. Uninstall. 
2. Windows asks if you want to remove all files:
   Image Added
   
   
   • Recommended - Click Yes if you have taken a backup of the necessary folders in

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

1. • .

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:

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.
   

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. Copy only the sections that are specific to your installation.

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

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