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/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 configuration files, compare your , you can find out by comparing your current 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.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:

   Code Block
   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 TmpCurrent/ conf directory with the your current installation's conf directory, for example:

   Code Block
   diff /opt/tomcat/conf TmpCurrent/tmp/tmpTomcat/conf

   
   

4. Make a note of any differences between your current installation and the test installationthe two configurations.
   You will need to reproduce these changes in the new installation . see 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.

Step 3  Move the current Tomcat installation into a backup

1. Stop Tomcat.

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

3. 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 MariaDB, use Database Driver to configure the additional library files required.

   
   

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

      
      

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

   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 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 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 you already have Tomcat is 9 installed in the tomcat base directory 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

In PowerShell, check the version

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:

Code Block
$env:JAVA_HOME="C:\Program Files\Java\jre1.8.0_282" $env:CATALINA_HOME="C:\app\tomcat9"

To check the version, in PowerShell enter:

Code Block
& "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

To find out what changes have been .

If you cannot remember what configuration changes you have made to Tomcat configuration files, compare you can compare your configuration files to those in a standard installation, as follows.

1. Download a new copy of your current version of TomcatUnpack .

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  Do not install it.

4. Use the compare command to find the differences between the TmpCurrent/ TempCurrent\conf files and those in your current installation's conf directory. For example, in PowerShell, enter:

   Code Block
   compare-object (get-content $tomcatc:\app\tomcat9\conf\file.xml) (get-content $standardInstallCurrentVersionTempCurrent\conf\file.xml)

   Compare In particular, you are looking for differences in 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 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:

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

   
   

7. Make a note of any extra files in current installation. see below'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:

   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

   
   

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 tomcat 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 tomcat/ 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 system's changes to the Java setup, including those required by PhixFlow. 
   
   Image Added
   In particular, note:
   • the path of the Java Virtual Machine

   • Java options

   Tip

   • . Make a note of any options you have added in addition to the PhixFlow recommendations. 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 )
4. Memory allocation
5. If tomcat

   • Memory allocation
6. 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

Image Removed

. 

Step 5 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
   
   
   • Recommended - Click Yes if you have taken a backup of the necessary folders in Step 3
   , click yes 
   Alternatively, click no so that Windows keeps
   • .
   • 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

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

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. 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 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, move copy them back into the new Tomcat installation, for example tomcattomcat9\secure and tomcat 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.

   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

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

   Code Block
   sudo systemctl start tomcat

   Test that Tomcat is running and the PhixFlow webapp can run:

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

   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:

   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. Assuming you have set the JAVA_HOME environment variable, in PowerShell, enter:

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