Please note, this guide is for instances already running VisibleThread 7.x.x and plan on upgrading to the latest version of VisibleThread 7. If you are currently running VT Docs 6.x and are looking to upgrade to VisibleThread 7, please see this guide for Ubuntu 24.04 systems: How-to-Upgrade-from-VT-Docs-to-VisibleThread-7-on-Ubuntu-24-04

As new versions of VisibleThread—formerly known as VT Docs—are released, we recommend upgrading your customer-hosted instance to:

• Access the latest features
• Apply security patches
• Receive performance and stability improvements

Important: Test the upgrade in a non-production environment before upgrading your production system. Take a backup or server snapshot before proceeding.

Prerequisites

Before starting the upgrade, confirm that your environment meets the following requirements.
This guide assumes you are using a local PostgreSQL database (PostgreSQL installed on the same server as VT).
 

System requirements

• Memory: 16 GB RAM
• Processor: 2 vCPUs
• Disk space: Approximately 100 GB available for /var/
• Ubuntu 24.04
• PostgreSQL: Version 16 or later (The above 24.04 OVA comes with PostgreSQL 16.9)
  To check your current PostgreSQL version, run:

psql --version

Backup requirements

Take a snapshot of the server before proceeding.

We also recommend creating a database backup by running the following commands

cd /home/visiblethread/VisibleThreadTools

sudo ./vt-backup.sh

Important: Confirm that the backup completed successfully before continuing with the upgrade.

Download the installers

Download the following tar.gz & .deb packages directly to your Ubuntu 24.04 based server.

VisibleThread 7.3.2.1

https://visiblethread.s3.us-east-1.amazonaws.com/public/download/VTRelease-7.3.2.1.tar.gz

MD5 checksum:

bdab6e9593e3f6ee92e6d4aa54e34c5a994fc66a

VTAPI

https://visiblethread.s3.us-east-1.amazonaws.com/public/download/visiblethread-api_1.0.13_amd64.deb

MD5 checksum:

f96cd2fe0decfff453691428612733524b423281

VTRAG

https://visiblethread.s3.us-east-1.amazonaws.com/public/download/vtrag_1.0.11_amd64.deb

MD5 checksum:

58eb6e4c54e34dc83acc70c8034d53ce5f45183d

You can use the checksums to confirm that the downloaded file has not been corrupted or modified.

Install the upgrade
 

Install VisibleThread 7.3.2.1

From the /VisibleThreadTools directory, run vt-upgrade.sh and point it at the tar.gz file to install the upgrade

cd /home/visiblethread/VisibleThreadTools

./vt-upgrade.sh /path/to/VTRelease-7.3.2.1.tar.gz

Wait for the upgrade script to complete successfully.

Monitor application startup

After the installation finishes, allow VisibleThread 7+ to start before proceeding with the remaining upgrade steps.

A database version migration runs automatically during the first startup after the upgrade. The time required depends on the size of the existing database.

Monitor the application log by running:

tail -f /home/visiblethread/tomcat/logs/catalina.out

Wait until the log displays a line containing something like:

INFO [main] org.apache.catalina.startup.Catalina.start Server startup in [202006] milliseconds

Note: Application startup may take 5–10 minutes or longer, depending on the size of the existing database. Do not proceed with the remaining upgrade steps until startup has completed.

After confirming that the application has started, press Ctrl+C to stop following the log. You can also verify startup is completed by navigating to your VT web server: https://myserver.example.com and seeing the login page.

Note: If you already have the latest versions of VTAPI and VTRAG installed, you do not need to reinstall them. To check which version you have installed, run:

apt list --installed 2>/dev/null | grep -Ei 'vtrag|visiblethread-api'

Install VTAPI (if applicable)

After confirming that VisibleThread has started successfully, install the VTAPI package.

From the directory containing the VTAPI .deb file, run:

sudo apt install ./visiblethread-api_1.0.13_amd64.deb

Install VTRAG (if applicable)

Install the VTRAG package.

From the directory containing the VTRAG .deb file, run:

sudo apt install ./vtrag_1.0.11_amd64.deb

Verify the upgrade

After the installer completes:

1. Open a supported web browser.
2. Navigate to:

https://myserver.example.com

4. Confirm that the VisibleThread sign-in screen loads.
5. Verify that the expected version number, such as 7.3.2.1, appears on the sign-in screen.
6. Sign in and confirm that the application is operating normally.

Bypass SSO for system administrator access

If Single Sign-On prevents you from accessing the standard sign-in screen, use the system administrator login URL:

/#/systemAdminLogin

For example:

https://myserver.example.com/#/systemAdminLogin

Sign in using an authorized VisibleThread system administrator account, then verify that the upgraded application and administrative features are working correctly. If you do not have any System Admin credentials, you can create a new set by following this guide: How to Create System Admin Logins with Back-end scripts.