Help Center Home

How can we help?

Search the knowledge base or browse by topic.

  1. VisibleThread Help Center
  2. VisibleThread 7+
  3. Deployment & Configuration
Follow

How to Upgrade from VT Docs to VisibleThread 7+ on RHEL Based Systems (RHEL 8, RHEL 9)

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+

If you are upgrading from a version of VisibleThread older than 7.0 you will need a new license file.

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


     
  • Operating system: RHEL 8, RHEL 9, OEL 8, OEL 9, etc.
  • VisibleThread version: 7.3.8
  • Environment Type: PROD or DEV
  • 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/
  • PostgreSQL: Version 16 or later
    To check your current PostgreSQL version, run:
psql --version


If your PostgreSQL version is lower than 16, follow the guide below to upgrade PostgreSQL on your RHEL-based system: How to Upgrade PostgreSQL to Version 16+ for VisibleThread 7+ on Red Hat 9
You MUST upgrade to PostgreSQL 16 before proceeding with the upgrade.
 

Backup requirements

Take a snapshot of the server before proceeding.

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

cd /opt/visiblethread/VisibleThreadTools"
sudo vt-backup.sh

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

 

Download the installers

Download the following RPM packages directly to your RHEL-based server.

VisibleThread 7.3.8

https://visiblethread.s3.us-east-1.amazonaws.com/public/download/visiblethread-docs-7.3.8-1.x86_64.rpm

MD5 checksum:

0ada4ff38a1798c3879832940d0cbe14

VTAPI

https://visiblethread.s3.us-east-1.amazonaws.com/public/download/visiblethread-api-1.0.14-1.x86_64.rpm

MD5 checksum:

372b4625b6b719fe27473e0cf093f4a3

VTRAG

https://visiblethread.s3.us-east-1.amazonaws.com/public/download/vtrag-1.0.12-1.x86_64.rpm

MD5 checksum:

15418e19c25b6900d8e491437a0e27af

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 directory containing the downloaded RPM file, run:

sudo yum install -y visiblethread-docs-7.3.8-1.x86_64.rpm

Wait for the installation command 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 /opt/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 RPM file, run:

sudo yum install -y visiblethread-api-1.0.14-1.x86_64.rpm

 

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:

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

Wait for the script to complete successfully before proceeding.
 

Install VTRAG

Install the VTRAG package.

From the directory containing the VTRA RPM file, run:

sudo yum install -y vtrag-1.0.12-1.x86_64.rpm

 

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:

sudo /opt/vtrag/setup/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
  1. Confirm that the VisibleThread sign-in screen loads.
  2. Verify that the expected version number, such as 7.3.8, appears on the sign-in screen.
  3. 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.

 

Known Issues + Troubleshooting

SSO stuck in a loop for system admin accounts [7.3+] (Fix available)

To resolve this issue, login with a system admin using the SSO bypass login: https://myserver.example.com/#/systemAdminLogin

If you do not have or know the system admin username and password, you can create a new set of credentials by following this guide: How-to-create-update-system-admin-user-using-backend-scripts

After logging in, locate the affected system admin user in the "Workspaces & Users > Users" tab. Click on the pencil to the right of the username. Check and then uncheck "licensed user" box. This should remove all permissions from the user. 

Next, remove that system admin user account from any workspaces in the "Workspaces & Users > Workspaces".

You should now be able to logout, and login to the system admin portal using SSO (normal URL) with your original system admin account.

For more assistance, please reach out to support@visiblethread.com

vtrag.env variables missing after upgrade [7.3+] (Fix available)

This a known bug - we are working on a fix. To resolve this issue now, you will need to re-enter and configure /etc/default/vtrag.env with your embeddings model values. Please see: How-to-Integrate-an-Embeddings-Model-for-VTRAG-in-VisibleThread-7

You will likely find your old values stored in the vtrag.env.bak file.

After setting up the vtrag.env, restart the vtrag service.

For more assistance, please reach out to support@visiblethread.com

"database collation version mismatch" when running provision.sh (Fix available)

This error is caused by upgrading the OS in place from RHEL 8 to RHEL 9. PostgreSQL’s data files were created on a system with glibc 2.28, which is RHEL 8. This server is now RHEL 9.7 with glibc 2.34.
 
It is strongly recommended to take a server snapshot and database backup before proceeding with the below.

To resolve this error:

run the following:
 

#reindex DB's to correct OS version of glibc

sudo -u postgres psql

\c postgres
REINDEX DATABASE postgres;
ALTER DATABASE postgres REFRESH COLLATION VERSION;

\c template1
REINDEX DATABASE template1;
ALTER DATABASE template1 REFRESH COLLATION VERSION;

\c visiblethread
REINDEX DATABASE visiblethread;
#allow time for the above command to run through each index, could take several minutes#

ALTER DATABASE visiblethread REFRESH COLLATION VERSION;

\q


(do not edit template0 DB)
 
Then, add an alias to the postgresql-17.service, so it can be recognized by our scripts:

sudo ln -s /usr/lib/systemd/system/postgresql-17.service /etc/systemd/system/postgresql.service
sudo systemctl daemon-reload
sudo systemctl restart postgresql
systemctl status postgresql

Then re-run provision.sh successfully with no errors.
Was this article helpful?
0 out of 0 found this helpful

Get Additional Help

Reach out to support@visiblethread.com to create a ticket.