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 RHEL systems: How-to-Upgrade-from-VT-Docs-to-VisibleThread-7-on-RHEL-Based-Systems-RHEL-8-RHEL-9
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/ -
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.5
MD5 checksum:
90b9f353869c58074af17e98019c7c5c
VTAPI
MD5 checksum:
54f4b8ed1f77d7bd9ef903dc3f43e31f
VTRAG
https://visiblethread.s3.us-east-1.amazonaws.com/public/download/vtrag-1.0.11-1.x86_64.rpm
MD5 checksum:
0499b447f6b1279aeb150a8278b60ffd
You can use the checksums to confirm that the downloaded file has not been corrupted or modified.
Install the upgrade
Install VisibleThread 7.3.5
From the directory containing the downloaded RPM file, run:
sudo yum install -y visiblethread-docs-7.3.5-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.
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:
rpm -qa | 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 RPM file, run:
sudo yum install -y visiblethread-api-1.0.13-1.x86_64.rpm
Install VTRAG (if applicable)
Install the VTRAG package.
From the directory containing the VTRA RPM file, run:
sudo yum install -y vtrag-1.0.11-1.x86_64.rpm
Verify the upgrade
After the installer completes:
- Open a supported web browser.
- Navigate to:
https://myserver.example.com
- Confirm that the VisibleThread sign-in screen loads.
- Verify that the expected version number, such as 7.3.5, appears on the sign-in screen.
- 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:
/#/systemAdminLoginFor example:
https://myserver.example.com/#/systemAdminLoginSign 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.
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
After setting up the vtrag.env, restart the vtrag service.
For more assistance, please reach out to support@visiblethread.com