Installing VisibleThread API and VT Docs 

This guide walks through installing VisibleThread API and VT Docs together. The VisibleThread API package is now a required dependency and must be installed before VT Docs.

The VisibleThread API package ships with a provisioning script (provision.sh) that can install and configure PostgreSQL and Java for you. Which parts of the script run are controlled by which lines are commented/uncommented, so review it before running.

Prerequisites

This guide assumes you have a running RHEL server with access to the repositories (repos).

The VisibleThread Docs .rpm has dependencies (httpd, openssl, java) that are available in the Red Hat repos. These packages are pulled in automatically by the .rpm file and do not need to be manually installed.

Note: VisibleThread will create a user called visiblethread upon installation — do not create a visiblethread user before installing.

Note: A sudoers file is available on request. It can be used to give a new OS user the minimum required permissions to install the rpm files. If you copy/paste its contents into a file in /etc/sudoers.d/, update the username in the file from vtuser to the username you'll be using, or create a user with that same name.

Minimum Server Spec

• 16GB RAM
• 2 CPU cores
• 100GB disk

Note: VisibleThread Docs requires port 443 and port 22, and sudo su permission to install correctly.

Note: Deployments have been tested on RHEL 8/9, and on VMware ESX vSphere/vCenter, Azure, and AWS.

Step 1: Download and Install the VisibleThread API

Download the appropriate .rpm for your version, then install it:

https://visiblethread.s3.us-east-1.amazonaws.com/public/download/visiblethread-api-1.0.10-1.x86_64.rpm
Checksum: 00da16f4ba72598b5d10829b3853efa7

sudo yum install -y /path/to/visiblethread-api-[version].rpm

This installs the provision.sh script (and its helper file lib.sh) to /usr/share/vtapi/setup/.

Step 2: Review the Provisioning Script

Before running it, review what the script will do:

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

The script is divided into modular functions:

• os_check — verifies the operating system is supported
• app_check — checks if VT API is already provisioned
• db_install — installs PostgreSQL locally
• db_config — configures the local PostgreSQL database
• db_remote_config — configures a connection to a remote PostgreSQL database
• java_install — installs Java 17
• fw_config — opens the required port (tcp/8084) on the firewall

By default, each of these lines is either commented out or active as follows:

• os_check and app_check are active — the OS is checked, and the script will refuse to run if VT API is already provisioned.
• db_install and db_config (local PostgreSQL) are active — the script installs and configures a local PostgreSQL database by default.
• db_remote_config is commented out.
• java_install is active — the script installs Java 17 for you by default.
• fw_config is commented out.

Step 3: Customize the Script for Your Environment

The defaults above (local PostgreSQL, Java installed by the script, no firewall changes) work for most single-server deployments. Edit the script only if you need something different:

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

Using a remote PostgreSQL database instead of local:

# Comment out these lines
# db_install || error_exit "Database installation failed."
# db_config || error_exit "Database configuration failed."

# Uncomment this line
db_remote_config || error_exit "Remote database configuration failed."

Before running the script, set the connection details in the API environment file:

sudo nano /etc/default/vtapi.env

The script will prompt for your remote DB admin username/password when run, then connect and bootstrap using the values from the environment file.

Skipping Java installation (if Java 17 is already installed on the server):

# Comment out this line
# java_install || error_exit "Java installation failed."

Opening the firewall port:

If VT Docs is on a different server to the API, uncomment fw_config to open tcp/8084. If they're on the same server, this is not normally required:

# Uncomment this line
fw_config || error_exit "Firewall configuration failed."

Step 4: Run the Provisioning Script

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

You'll be prompted to confirm before the script proceeds. Once complete, it starts the vtapi.service.

Step 5: Download and Install VT Docs

The VT Docs .rpm is available to download here:

https://visiblethread.s3.us-east-1.amazonaws.com/public/download/visiblethread-docs-7.2.1-1.x86_64.rpm
Checksum: 7883e15251988d84a6f810cd2aa9f59d

sudo yum install -y /path/to/visiblethread-docs-7.2.1-1.x86_64.rpm

To verify the download completed successfully, check the MD5 hash:

md5sum visiblethread-docs-7.2.1-1.x86_64.rpm

The valid MD5 hash is 538070cd9cb371c952ea2e471a2e94cc.

Step 6: Check if fapolicyd Is Installed

If fapolicyd is installed, it will block Apache Tomcat from being installed correctly unless the required directory is whitelisted.

Check if fapolicyd is installed:

sudo systemctl status fapolicyd

• If fapolicyd is not installed, you can ignore this section.
• If fapolicyd is installed, whitelist the install directory for Apache Tomcat:

# as root user
echo "allow perm=any uid=visiblethread : dir=/opt/visiblethread/tomcat/" >> /etc/fapolicyd/rules.d/01-visiblethread.rules

fapolicyd-cli --update

systemctl restart fapolicyd

sudo systemctl restart visiblethread-docs.service

Post-Installation

Verify the API service:

sudo systemctl status vtapi.service

Verify the VT Docs service:

sudo systemctl status visiblethread-docs.service

Check provisioning logs if something went wrong:

sudo cat /var/log/vt-api-provision.log