Overview

This guide provides step-by-step instructions for manually upgrading Apache Tomcat in your VT Docs installation. The upgrade process maintains all your custom configurations while updating to the latest Tomcat version for improved security and performance.

Important: This upgrade is only supported for VT Docs version 6.0 or higher.

Prerequisites

• VT Docs version 6.0 or higher must be installed and running
• Administrator/root privileges required
• Latest Apache Tomcat 9.x zip file downloaded from the official Apache website

Download Tomcat

1. Visit the Apache Tomcat 9 download page
2. Download the 64-bit Windows zip file (apache-tomcat-9.x.x-windows-x64.zip)
   • Note: Use the Windows zip file for both Linux and Windows installations
   • The filename containing "windows" does not affect Linux compatibility

Upgrade Methods

We provide automated scripts for both Windows and Linux systems. Choose the appropriate method for your operating system.

Windows Upgrade

Requirements

• PowerShell with Administrator privileges
• VT Docs service must be running before starting the upgrade

Steps

1. Download the upgrade script (vt-upgrade-tomcat.ps1) to your system: https://visiblethread.s3.us-east-1.amazonaws.com/public/download/vt-upgrade-tomcat.sh
2. Open PowerShell as Administrator
3. Navigate to the script directory
4. Run the upgrade command:

   .\vt-upgrade-tomcat.ps1 "C:\path\to\apache-tomcat-9.x.x-windows-x64.zip"
   

What the script does:

• Verifies VT Docs version compatibility (6.0+)
• Compares current Tomcat version with upgrade version
• Stops the VT Docs service safely
• Backs up current Tomcat installation
• Preserves custom configuration files
• Installs new Tomcat version
• Restores custom configurations
• Updates file permissions
• Restarts VT Docs service

Linux Upgrade

Requirements

• Root privileges (use sudo)
• VT Docs service must be running before starting the upgrade

Steps

1. Download the upgrade script (vt-upgrade-tomcat.sh) to your system: https://visiblethread.s3.us-east-1.amazonaws.com/public/download/vt-upgrade-tomcat.sh
2. Make the script executable:

   chmod +x vt-upgrade-tomcat.sh
   

3. Run the upgrade command with sudo:

   sudo ./vt-upgrade-tomcat.sh /path/to/apache-tomcat-9.x.x-windows-x64.zip
   

What the script does:

• Detects your Linux distribution (Ubuntu, RHEL, CentOS, Fedora)
• Verifies VT Docs version compatibility (6.0+)
• Compares current Tomcat version with upgrade version
• Stops the VT Docs service safely
• Backs up current Tomcat installation to tar.gz
• Preserves custom configuration files and dashboard
• Installs new Tomcat version
• Restores custom configurations
• Updates file permissions and ownership
• Restarts VT Docs service

Configuration Files Preserved

The upgrade process automatically preserves these critical configuration files:

Core Configuration

• server.xml - Server configuration and connectors
• context.xml - Application context settings
• web.xml - Web application deployment descriptor
• catalina.properties - Catalina engine properties
• logging.properties - Logging configuration
• tomcat-users.xml - User authentication settings

Custom Components

• ROOT.xml - VT Docs application context
• catalina.bat/sh - Startup script customizations
• setenv.sh (Linux only) - Environment variables
• dashboard/ directory - Custom dashboard files

Safety Features

Automatic Backup

• Windows: Creates tomcat_backup.zip in the installation directory
• Linux: Creates tomcat_backup.tar.gz in the installation directory
• Backup includes complete current Tomcat installation
• Option to remove backup after successful upgrade

Version Validation

• Prevents downgrading to older Tomcat versions
• Confirms upgrade file contains valid Tomcat 9.x version
• Validates VT Docs compatibility before proceeding

Service Management

• Graceful service shutdown with timeout protection
• Automatic service restart after upgrade
• Service status validation before and after upgrade

Troubleshooting

Common Issues

"VT Docs is not running" Error

• Ensure VT Docs service is started before running the upgrade
• Check service status in Windows Services or systemctl status on Linux

"VT Docs Version must be 6 or higher" Error

• This upgrade is only compatible with VT Docs 6.0+
• Contact support for upgrading older VT Docs versions

"Script must be run with administrator/root privileges" Error

• Windows: Run PowerShell as Administrator
• Linux: Use sudo when executing the script

Service fails to restart after upgrade

• Check the backup file is available for rollback
• Review VT Docs logs for specific error messages
• Contact VisibleThread Support with error details

Rollback Procedure

If issues occur after upgrade:

1. Stop VT Docs service
2. Remove the new tomcat directory
3. Restore from backup:
   • Windows: Extract tomcat_backup.zip
   • Linux: Extract tomcat_backup.tar.gz
4. Restart VT Docs service

Post-Upgrade Verification

After successful upgrade:

1. Verify VT Docs is accessible through your web browser
2. Check application functionality - login, document processing, etc.
3. Review logs for any error messages
4. Test key features to ensure everything works correctly

Support

If you encounter issues during the upgrade process:

• Preserve backup files - do not delete them until upgrade is confirmed successful
• Collect error messages and log files
• Note your current VT Docs version and target Tomcat version
• Contact VisibleThread Support with detailed information about the issue

Notes

• The upgrade process typically takes 2-5 minutes depending on system performance
• VT Docs will be temporarily unavailable during the upgrade
• All custom configurations and data are preserved
• The upgrade only affects the Tomcat web server, not your VT Docs data or database

---