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:
- Standard Installation (Recommended) — Apache web server and local PostgreSQL database.
- IIS Web Server — Microsoft IIS instead of the bundled Apache web server.
- 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
- Locate the downloaded installer:
vtdocs_windows-x64_7_4_2.exe
- Double-click the installer to start the installation wizard.
- 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.
- Continue through the installer.
- 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:
- Under License File, click Browse and choose your VisibleThread 7 license file.
- Enter the System Admin User (an email address), First Name and Last Name.
- Enter and confirm a password.
- 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
- Locate and run:
vtdocs_windows-x64_7_4_2.exe
- Proceed through the installation wizard until you reach the component selection screen.
- Clear the Apache checkbox.
Leave PostgreSQL selected if the server will use the locally installed PostgreSQL database.
- Continue through the installation wizard.
- 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
- Locate and run:
vtdocs_windows-x64_7_4_2.exe
- Proceed through the installation wizard until you reach the component selection screen.
- 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.
- Continue through the installation wizard.
- Allow the installation to complete. The installer does not ask for database details.
- 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;
TheGRANTline is needed on PostgreSQL 16 and later when the administrator is not a superuser, as on Amazon RDS. - 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. - Point VisibleThread at the database. In
C:\Program Files\VisibleThread\vtdocs\visiblethread.env, replace thevtdocs.databaselines (the installer writes them forlocalhost) with:vtdocs.database.host=<your-database-host> vtdocs.database.port=5432 vtdocs.database.name=visiblethread vtdocs.database.username=visiblethread vtdocs.database.password=<database-password>
- Restart the
vtdocs-tomcatservice. On the first start VisibleThread upgrades the schema, which can take a few minutes. - 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 withmust be able to SET ROLE "vtapi". Grant the role and run the script again; the second run reportsrole "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 inC:\Program Files\VisibleThread\vtdocs\incl\vtapi.env.ps1set$DB_API_WORKER_SERVER = "<your-database-host>"and restart thevtdocs-vtapiservice. - If you installed VTRAG, move it to the database the same way. The server must allow the
vectorextension (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 inC:\Program Files\VisibleThread\vtdocs\incl\vtrag.env.ps1set$VTRAG_DB_HOST = "<your-database-host>", set your embeddings model (see Set up VTRAG), and restart thevtdocs-vtragservice. - 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:
- 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. - Run the installer for the version you already have, as administrator.
- On the components screen, select VTRAG and leave the other components as they are. The installer keeps your existing installation and data.
- 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.