How can we help?

Search the knowledge base or browse by topic.

Follow

How to Deploy VisibleThread 7+ on Windows

This guide describes how to install VisibleThread 7 on a fresh Windows Server.

VisibleThread can be deployed on Windows using one of the following configurations:

  1. Standard Installation (Recommended) — Apache web server and local PostgreSQL database.
  2. IIS Web Server — Microsoft IIS instead of the bundled Apache web server.
  3. External Database — An externally hosted PostgreSQL database instead of the bundled local PostgreSQL instance.

System requirements

Before installing VisibleThread, confirm that the server meets the minimum requirements.

  • Memory: 16 GB RAM
  • Processor: 2 CPU cores
  • Disk space: 100 GB

VisibleThread Windows installations have been tested and verified on:

  • Windows Server 2016
  • Windows Server 2019
  • Windows Server 2022
  • Windows Server 2025

Important: VisibleThread requires TCP port 443 to be accessible to users connecting to the application through a web browser.

Download VisibleThread

Download the VisibleThread 7.4.2 Windows installer:

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

Verify the installer

After downloading the installer, you can verify the MD5 checksum from a Windows Command Prompt:

certutil -hashfile vtdocs_windows-x64_7_4_2.exe MD5

The expected MD5 checksum is:

be67ae6b37b7fb40a8a0297b0e42fb67

Important: If the calculated checksum does not match the value above, download the installer again before continuing.

 

 

Standard Installation (Recommended)

The standard installation is the recommended deployment method for most customer-hosted VisibleThread environments.

This configuration installs:

  • VisibleThread
  • Apache HTTP Server
  • Local PostgreSQL 17 database

Apache is configured automatically as the reverse proxy for VisibleThread.

Run the installer

  1. Locate the downloaded installer:
vtdocs_windows-x64_7_4_2.exe
  1. Double-click the installer to start the installation wizard.
  2. Proceed through the installation wizard until you reach the component selection screen.

The component selection screen lists five components. For a standard installation, leave all five selected:

  • VT Docs - the VisibleThread application.
  • Apache - the web server.
  • Postgres - a local PostgreSQL 17 database.
  • VTRAG - the service behind the AI features that search your documents. It needs an embeddings model, which you set after installation (see Set up VTRAG).
  • VTAPI - the VisibleThread API service.

Note: Apache is installed and configured automatically as part of the VisibleThread installation. No additional reverse proxy configuration is required for a standard deployment.

  1. Continue through the installer.
  2. Allow the installation to complete.

Verify the installation

After the installer completes, allow several minutes for VisibleThread to start.
 

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"

 

Open a supported web browser and navigate to:

https://<VisibleThreadServerAddress>

A new server opens the Setup VT Docs Instance page. Complete it:

  1. Under License File, click Browse and choose your VisibleThread 7 license file.
  2. Enter the System Admin User (an email address), First Name and Last Name.
  3. Enter and confirm a password.
  4. Click Submit. When the confirmation says the instance was created, click OK.

Sign in with the account you just created.

 

 

IIS Web Server Installation

Use this deployment method when Microsoft IIS will provide the reverse proxy and SSL termination instead of the bundled Apache web server.

Important: The VisibleThread installer does not configure IIS automatically. IIS must be configured separately after the VisibleThread installation completes.

Run the installer

  1. Locate and run:
vtdocs_windows-x64_7_4_2.exe
  1. Proceed through the installation wizard until you reach the component selection screen.
  2. Clear the Apache checkbox.

Leave PostgreSQL selected if the server will use the locally installed PostgreSQL database.

  1. Continue through the installation wizard.
  2. Allow the installation to complete.

Configure IIS

After the VisibleThread installation completes, configure Microsoft IIS as the reverse proxy and SSL termination point for VisibleThread.

Follow: IIS as a Reverse Proxy for VT Docs

Complete the IIS configuration before attempting to make VisibleThread available to end users.

Verify the installation

After configuring IIS, navigate to:

https://<VisibleThreadServerAddress>

Confirm that:

  • The Setup VT Docs Instance page loads on a new server (the sign-in page once setup is complete).
  • HTTPS is functioning correctly.
  • IIS successfully proxies requests to VisibleThread.
  • You can sign in to the application.

 

External Database Installation

Use this deployment method when VisibleThread will connect to an externally hosted PostgreSQL database rather than installing PostgreSQL locally on the VisibleThread server.

The external PostgreSQL database should be provisioned and accessible from the VisibleThread server before beginning the installation.

Run the installer

  1. Locate and run:
vtdocs_windows-x64_7_4_2.exe
  1. Proceed through the installation wizard until you reach the component selection screen.
  2. Clear the PostgreSQL checkbox.

If you want the installer to configure Apache as the VisibleThread reverse proxy, leave Apache selected.

If the deployment will use IIS instead, clear both Apache and PostgreSQL.

The available configurations are therefore:

  • Apache + external PostgreSQL: Leave Apache selected and clear PostgreSQL.
  • IIS + external PostgreSQL: Clear both Apache and PostgreSQL.
  1. Continue through the installation wizard.
  2. Allow the installation to complete. The installer does not ask for database details.
  3. Prepare the database. On the database server, as an administrator (on Amazon RDS, the master user), create the VisibleThread role and database:
    CREATE USER visiblethread WITH PASSWORD '<database-password>' NOSUPERUSER INHERIT CREATEDB NOCREATEROLE NOREPLICATION;
    GRANT visiblethread TO CURRENT_USER;
    CREATE DATABASE visiblethread WITH OWNER = visiblethread ENCODING = 'UTF8' TEMPLATE = template0;
    The GRANT line is needed on PostgreSQL 16 and later when the administrator is not a superuser, as on Amazon RDS.
  4. Load the VisibleThread schema into the new database. The installer includes a PostgreSQL client and the schema file. In PowerShell on the VisibleThread server:
    $env:PGPASSWORD = "<database-password>"
    & "C:\Program Files\VisibleThread\vtdocs\PostgreSQL\17\bin\psql.exe" -h <your-database-host> -U visiblethread -d visiblethread -q -f "C:\Program Files\VisibleThread\vtdocs\setup\vt_db_setup.sql"
    VisibleThread does not start against an empty database; this step is required.
  5. Point VisibleThread at the database. In C:\Program Files\VisibleThread\vtdocs\visiblethread.env, replace the vtdocs.database lines (the installer writes them for localhost) with:
    vtdocs.database.host=<your-database-host>
    vtdocs.database.port=5432
    vtdocs.database.name=visiblethread
    vtdocs.database.username=visiblethread
    vtdocs.database.password=<database-password>
  6. Restart the vtdocs-tomcat service. On the first start VisibleThread upgrades the schema, which can take a few minutes.
  7. Move VTAPI to the database. The installer cannot create its database on an external server, so run its script as the administrator. In PowerShell:
    $env:PGPASSWORD = "<admin-password>"
    & "C:\Program Files\VisibleThread\vtdocs\PostgreSQL\17\bin\psql.exe" -h <your-database-host> -U <admin-user> -d postgres -f "C:\Program Files\VisibleThread\vtdocs\setup\vtapi.sql"
    On Amazon RDS, or any PostgreSQL 16+ server where the administrator is not a superuser, this first run stops with must be able to SET ROLE "vtapi". Grant the role and run the script again; the second run reports role "vtapi" already exists, which is expected:
    & "C:\Program Files\VisibleThread\vtdocs\PostgreSQL\17\bin\psql.exe" -h <your-database-host> -U <admin-user> -d postgres -c "GRANT vtapi TO CURRENT_USER;"
    & "C:\Program Files\VisibleThread\vtdocs\PostgreSQL\17\bin\psql.exe" -h <your-database-host> -U <admin-user> -d postgres -f "C:\Program Files\VisibleThread\vtdocs\setup\vtapi.sql"
    Then in C:\Program Files\VisibleThread\vtdocs\incl\vtapi.env.ps1 set $DB_API_WORKER_SERVER = "<your-database-host>" and restart the vtdocs-vtapi service.
  8. If you installed VTRAG, move it to the database the same way. The server must allow the vector extension (pgvector; available on Amazon RDS for PostgreSQL):
    & "C:\Program Files\VisibleThread\vtdocs\PostgreSQL\17\bin\psql.exe" -h <your-database-host> -U <admin-user> -d postgres -f "C:\Program Files\VisibleThread\vtdocs\setup\vtrag.sql"
    Then in C:\Program Files\VisibleThread\vtdocs\incl\vtrag.env.ps1 set $VTRAG_DB_HOST = "<your-database-host>", set your embeddings model (see Set up VTRAG), and restart the vtdocs-vtrag service.
  9. Check both services. Each should return HTTP 200:
    curl.exe -s -o NUL -w "%{http_code}" http://localhost:8084/actuator/health
    curl.exe -s -o NUL -w "%{http_code}" http://localhost:8010/actuator/health

Important: Ensure that the VisibleThread server can communicate with the external PostgreSQL server and that any required firewall rules, database permissions, and network access have been configured before completing the installation.

 

Verify the installation

After installation, allow VisibleThread several minutes to start and connect to the external database.

Navigate to:

https://<VisibleThreadServerAddress>

Confirm that:

  • The Setup VT Docs Instance page loads on a new server (the sign-in page once setup is complete).
  • VisibleThread can connect to the external PostgreSQL database.
  • You can sign in to the application.
  • The selected web server configuration is operating correctly.

 

 

 

 

Set up VTRAG

VTRAG powers the AI features that search your documents. If you selected the VTRAG component, it runs as the vtdocs-vtrag service and VisibleThread is already configured to reach it.

Add VTRAG to an existing install

If VisibleThread is installed without VTRAG:

  1. Stop all the VisibleThread services. In PowerShell as administrator:
    Get-Service vtdocs-* | Stop-Service -Force
    If they are running, the installer cannot replace its files, stops with Could not remove the previous VT Docs vtapi and vtrag files, and rolls back.
  2. Run the installer for the version you already have, as administrator.
  3. On the components screen, select VTRAG and leave the other components as they are. The installer keeps your existing installation and data.
  4. When it finishes, start any VisibleThread service that is still stopped. The installer does not restart vtdocs-vtapi:
    Get-Service vtdocs-* | Start-Service

With the bundled PostgreSQL, the installer creates the vtrag database. With an external PostgreSQL server, set it up as in the external database section above.

Connect your embeddings model

VTRAG ships set up for a placeholder model. Edit C:\Program Files\VisibleThread\vtdocs\incl\vtrag.env.ps1 as administrator and set your provider as described in How to Integrate an Embeddings Model for VTRAG in VisibleThread 7+, using its Windows format. Leave the database settings and the Do Not Modify block as they are.

Restart VTRAG and check it:

Restart-Service vtdocs-vtrag
curl.exe -s -o NUL -w "%{http_code}" http://localhost:8010/actuator/health

The health check should print 200. VTRAG can take a minute to start. If it does not, check C:\Program Files\VisibleThread\vtdocs\logs\vtrag.log.

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

Get Additional Help

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