Please note, this guide is for deployments currently on VT Docs 6.x, looking to upgrade to VisibleThread 7.x.

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.

Request New License File for VisibleThread 7+

VisibleThread 7+ requires a newly formatted license file. Email support@visiblethread.com to request the new license file.

Include ALL of the following information in your request:

• A Screenshot of your existing license page, showing license information like so
  
  
   
• Environment Type: PROD or DEV
• Operating system: Ubuntu 24.04
• VisibleThread version: 7.3.8
• Your organization name

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
  If you are running a version lesser than 24.04, you must deploy the VT Docs 6.2.1 Ubuntu 24.04 OVA, and migrate your existing data over first.
  1. Deploy The 24.04 OVA: vtdocs-6.2.1_ubnt2404.ova
  2. Migrate existing data to the new 24.04 OVA, by following this guide: How To Migrate From One Server To Another With VisibleThread 7+
  
  WARNING: Upgrading the OS in place (ex: 20.04 > 22.04 > 24.04) will NOT work and will break the VT Docs application. You must deploy the 24.04 OVA first and migrate before proceeding.
   
• 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.8

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

MD5 checksum:

35396c82ec8205fae95e2a7f3dc925f0

VTAPI

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

MD5 checksum:

2d8445e0f1dd3228f0b674e730ed2ebe

VTRAG

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

MD5 checksum:

ae4d63defea7007282b7cce704b80177

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

Install the upgrade
 

Install VisibleThread 7.3.8

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

Install VTAPI

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.14_amd64.deb

Configure and provision VTAPI

After installing the VTAPI package, open the provisioning script:

sudo nano /usr/share/vtapi/setup/provision.sh

In the script, locate and comment out only the following lines:

java_install
db_install

The updated lines should appear as:

# java_install
# db_install

Important: Do not comment out or modify any other lines in the provisioning script.

Save the changes and exit Nano:

1. Press Ctrl+O, then press Enter to save.
2. Press Ctrl+X to exit.

Run the provisioning script:

cd /usr/share/vtapi/setup

sudo ./provision.sh

Wait for the script to complete successfully before proceeding.
 

Install VTRAG

Install the VTRAG package.

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

sudo apt install ./vtrag_1.0.12_amd64.deb

Configure and provision VTRAG

After installing the VTRAG package, open the provisioning script:

sudo nano /opt/vtrag/setup/provision.sh

In the script, locate and comment out only the following lines:

java_install
db_install

The updated lines should appear as:

# java_install
# db_install

Important: Do not comment out or modify any other lines in the provisioning script.

Save the changes and exit Nano:

1. Press Ctrl+O, then press Enter to save.
2. Press Ctrl+X to exit.

Run the provisioning script:

cd /opt/vtrag/setup

sudo ./provision.sh

Wait for the script to complete successfully before proceeding.
 

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

Upload the new license file

After receiving the new license file from VisibleThread support, apply the new license file by clicking Upload License under the System Admin > License tab.