Help Center Home

VisibleThread -
Help Center Find helpful articles on different VisibleThread Products

  1. VisibleThread Help Center
  2. Deployments
  3. VisibleThread 7+ - Customer Hosted Deployments
Follow

How to Upgrade VisibleThread 7+ on Windows

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 Windows: How-to-Upgrade-from-VT-Docs-to-VisibleThread-7-on-Windows

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 on the drive where VT Docs is installed

Backup requirements

Take a snapshot of the server before proceeding.

We also recommend creating a database backup by running the following commands from an elevated Windows Command Prompt:

cd "C:\Program Files\visiblethread\vtdocs\VisibleThreadTools"
vt-backup.bat

Important: Confirm that the backup completed successfully before continuing with the upgrade. Your backup file will be saved in C:\Program Files\visiblethread\vtdocs\VisibleThreadTools\vtbackups


What the Windows installer upgrades

VisibleThread upgrades for Windows are distributed as .exe installer files.

The VisibleThread 7+ Windows installer:

  • Upgrades a local PostgreSQL installation to PostgreSQL 17
  • Includes VTRAG
  • Includes VTAPI

Download the installer

Download the VisibleThread 7.3.5 Windows installer directly to the Windows server:

https://visiblethread.s3.us-east-1.amazonaws.com/public/download/vtdocs_windows-x64_7_3_5.exe

MD5 checksum:

a7b5980324c6bd4ece27c73664f599d3

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

Install the upgrade

  1. Stop the vtdocs-tomcat, vtdocs-vtapi, and vtdocs-vtrag services before running the .exe
  2. Locate the downloaded .exe file on the Windows server.
  3. Double-click the installer.
  4. Follow the on-screen instructions.
  5. Select the installation options appropriate for your environment.

Standard installation

Use the standard installation options when your deployment uses:

  • Apache
  • A local PostgreSQL database

Leave all installation options selected, and then click Next.

Wait for the installer to complete.

Important: After installation, VisibleThread may take 5–10 minutes to start for the first time. The startup time depends on the size of your database.

 

Non-standard installation (IIS or External DB)

Adjust the installation options when your environment uses IIS or an external PostgreSQL database.

IIS deployment

When using IIS instead of Apache:

  1. Clear the Apache option.
  2. Click Next.

External PostgreSQL database

When using an external PostgreSQL database:

  1. Clear the PostgreSQL option.
  2. Click Next.

Important: Only select the PostgreSQL upgrade when PostgreSQL is installed locally and managed by the VisibleThread installer.

 

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 the following command in CMD (not PowerShell):

powershell -NoProfile -Command "Get-Content -Path 'C:\Program Files\VisibleThread\vtdocs\tomcat\logs\vtdocs.log' -Tail 20 -Wait"

Wait until the log displays a line containing something like:

Started VTApplication in 38.997 seconds

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.

You can also verify startup is completed by navigating to your VT web server: https://myserver.example.com and seeing the login page.

 

Verify the upgrade

After the installer completes:

  1. Allow 5–10 minutes for the application to start.
  2. Open a supported web browser.
  3. 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.4, 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.

 

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

Windows installer does not remove previous version of PostgreSQL 14 [7+] (Fix available)

If you still have PostgreSQL 14 (App should be using PostgreSQL 17 post upgrade) installed on your VisibleThread 7 server, you can safely remove it by following these steps:

  • Take DB Backup: https://support.visiblethread.com/hc/en-us/articles/214225306-Backing-up-and-restoring-VisibleThread-data
  • Uninstall PostgreSQL 14 in the control panel
  • Reboot the server
  • Start PostgreSQL17 manually
    cd "C:\Program Files\Visiblethread\vtdocs\PostgreSQL\17\bin"
    pg_ctl -D "C:\Program Files\Visiblethread\vtdocs\PostgreSQL\17\data" start
  • Recreate the vtdocs-postgres service
    pg_ctl register -N "vtdocs-postgres" -D "C:\Program Files\Visiblethread\vtdocs\PostgreSQL\17\data"
  • Check the POSTGRESQL_HOME System Environment variable to point to the new PostgreSQL directory

    Press Win → type environment variables → open Edit the system environment variables
    Click Environment Variables…
    Under System variables (or User variables if that’s where it exists), find POSTGRESQL_HOME
    Click edit > select new PostgreSQL directory, likely will be c:\program files\visiblethread\vtdocs\postgresql
  • Start vtdocs-postgres in the services
     

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

"Failed to update database info" error after installer runs [7+] (Fix available)

You can safely ignore / close this error. It is a false positive.

"VisibleThread\vtdocs\jre\bin\java.dll Could not create this file" [7.2+] (Fix available)

This is occurring because one or more of the following services were still running when you ran the installer: vtdocs-tomcat, vtdocs-vtapi, vtdocs-vtrag.

Open services, and ensure they are all stopped. Then click "Yes" to try again. This should resolve the issue and allow the installer to continue.
 

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

File uploads stuck spinning - Server using IIS instead of Apache [7+] (Fix available)

Navigate to IIS, go to the server level, then open ARR (Application Request Routing), then update the 'Response buffer threshold (KB)' value to 0.


Then restart your IIS VT website.

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

Home page keep reloading after login - Server using IIS instead of Apache [7+] (Fix available)

Navigate to IIS, go to the server level, then open ARR (Application Request Routing), then uncheck the ‘Reverse rewrite host in response headers’ setting.

Then restart your IIS VT website.

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

 

 

 

 

 

Was this article helpful?
0 out of 0 found this helpful

Get Additional Help

Visit our Helpdesk for additional help and support.