This guide installs VisibleThread 7 on a single RHEL 8 or RHEL 9 server: the VisibleThread API (VTAPI) first, then VisibleThread, then VTRAG for the AI features. On a server at the minimum spec the installs take about 5 minutes.
Before you start
You need:
- A RHEL 8 or RHEL 9 server with its Red Hat repositories enabled, either through a Red Hat subscription or, on AWS and Azure, through Red Hat Update Infrastructure (RHUI).
- At least 16 GB RAM, 2 CPU cores and 100 GB disk.
- Root or sudo access, and ports 22 and 443 open.
- Your VisibleThread 7 license file. You upload it at the end.
Do not create a visiblethread user first. The package creates it.
If you install as a non-root user, support can provide a sudoers file with the minimum permissions needed to install the packages.
Step 1: Install the VisibleThread API
Download the VTAPI package and check it:
curl -O https://visiblethread.s3.us-east-1.amazonaws.com/public/download/visiblethread-api-1.0.14-1.x86_64.rpm
md5sum visiblethread-api-1.0.14-1.x86_64.rpm
The MD5 should be 372b4625b6b719fe27473e0cf093f4a3.
Install it:
sudo yum install -y ./visiblethread-api-1.0.14-1.x86_64.rpm
This adds the provisioning script at /usr/share/vtapi/setup/provision.sh.
Step 2: Run the provisioning script
The script installs PostgreSQL 16 and Java 17, creates the databases, and starts VTAPI. The defaults suit a single server with a local database, so most installs run it unchanged:
sudo /usr/share/vtapi/setup/provision.sh
Answer y when it asks you to confirm. It ends with Finished provisioning.
The script is a list of steps, and you turn a step off by commenting out its line. These are the defaults:
| Step | Default | What it does |
|---|---|---|
os_check |
on | Checks the operating system |
app_check |
on | Stops if VTAPI is already provisioned |
db_install |
on | Installs PostgreSQL locally |
db_config |
on | Configures the local database |
db_remote_config |
off | Uses a remote PostgreSQL instead |
java_install |
on | Installs Java 17 |
fw_config |
off | Opens tcp/8084 in the firewall |
Change them only if you need to:
- External PostgreSQL server: follow Use an external PostgreSQL server instead of running the script unchanged.
-
Java 17 already installed: comment out
java_install. -
VTAPI on a different server from VisibleThread: uncomment
fw_config.
If something fails, the log is /var/log/vt-api-provision.log.
Step 3: Install VisibleThread
Download the VisibleThread package and check it:
curl -O https://visiblethread.s3.us-east-1.amazonaws.com/public/download/visiblethread-docs-7.4.2-1.x86_64.rpm
md5sum visiblethread-docs-7.4.2-1.x86_64.rpm
The MD5 should be 404563c6b3221e9f34097306da43ff24.
Install it:
sudo yum install -y ./visiblethread-docs-7.4.2-1.x86_64.rpm
The package starts the visiblethread-docs service itself.
Step 4: If fapolicyd is installed, allow Tomcat
Check whether fapolicyd is installed:
sudo systemctl status fapolicyd
If it is not installed, skip this step. If it is, allow the Tomcat directory and restart:
echo "allow perm=any uid=visiblethread : dir=/opt/visiblethread/tomcat/" | sudo tee -a /etc/fapolicyd/rules.d/01-visiblethread.rules
sudo fapolicyd-cli --update
sudo systemctl restart fapolicyd
sudo systemctl restart visiblethread-docs
Step 5: Check the services
sudo systemctl status vtapi
sudo systemctl status visiblethread-docs
Both should show active (running).
Step 6: Install VTRAG
VTRAG powers the AI features that search your documents. It needs PostgreSQL 16, which step 2 installed. If you are adding VTRAG to an older server that still runs an earlier PostgreSQL, upgrade it first with How to Upgrade PostgreSQL to Version 16+ for VisibleThread 7+ on Red Hat 8 & 9.
Download the package, check it, and install it:
curl -O https://visiblethread.s3.us-east-1.amazonaws.com/public/download/vtrag-1.0.12-1.x86_64.rpm
md5sum vtrag-1.0.12-1.x86_64.rpm
sudo yum install -y ./vtrag-1.0.12-1.x86_64.rpm
The MD5 should be 15418e19c25b6900d8e491437a0e27af.
Set your embeddings model in /etc/default/vtrag.env as described in How to Integrate an Embeddings Model for VTRAG in VisibleThread 7+. Leave the database settings as they are.
PostgreSQL 16 and Java 17 are already installed, so turn those steps off in /opt/vtrag/setup/provision.sh by commenting out these two lines. Leave pgvector_install and db_config on.
#db_install || error_exit "Error installing PostgreSQL."
#java_install || error_exit "Error installing Java."
Run it, answering y to confirm:
sudo /opt/vtrag/setup/provision.sh
Check VTRAG:
sudo systemctl status vtrag
curl -s -o /dev/null -w '%{http_code}\n' http://localhost:8010/actuator/health
The service should be active (running) and the health check should print 200. VisibleThread is already configured to reach VTRAG on the same server.
Step 7: Complete setup in the browser
Browse to https://<your-server>/. A new server opens the Setup VT Docs Instance page. Every address goes to this page until setup is complete, including the system admin sign-in.
- 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. A new server opens at System Admin > Workspaces & Users, with a Default Sandbox workspace and the license count from your file.
Next, connect your LLM under System Admin > Generative AI to turn on the AI features.
Use an external PostgreSQL server
VisibleThread, VTAPI and VTRAG can all use an external PostgreSQL 16 or later server, such as Amazon RDS, instead of a local one. You need an admin account on that server that can create databases and roles. For VTRAG, the server must have the pgvector extension available; Amazon RDS includes it.
Follow these steps in place of the default step 2, and after step 3 and step 6.
1. Install the PostgreSQL client
sudo dnf module enable -y postgresql:16
sudo dnf install -y postgresql
2. VTAPI
After step 1, edit /etc/default/vtapi.env. Set DB_API_WORKER_SERVER to your server's address and DB_API_WORKER_PASS to a new password for the VTAPI database user.
In /usr/share/vtapi/setup/provision.sh, comment out db_install and db_config, and uncomment db_remote_config. Then run it:
sudo PGDATABASE=postgres /usr/share/vtapi/setup/provision.sh
Answer y to both questions, then enter the admin user and password. PGDATABASE=postgres is needed when the admin user has no database of its own name, as on Amazon RDS; without it the script stops with database "<admin user>" does not exist.
3. VisibleThread
After step 3, create the VisibleThread database user and database, with your own password:
psql -h <db-server> -U <admin-user> -d postgres
CREATE ROLE visiblethread WITH LOGIN PASSWORD '<password>' CREATEDB;
GRANT visiblethread TO CURRENT_USER;
CREATE DATABASE visiblethread WITH OWNER = visiblethread ENCODING = 'UTF8' LC_COLLATE = 'en_US.UTF-8' LC_CTYPE = 'en_US.UTF-8' TEMPLATE = template0;
\q
Load the starting schema as the new user:
psql -h <db-server> -U visiblethread -d visiblethread -f /opt/visiblethread/setup/vt_db_setup.sql
Point VisibleThread at the server in /etc/default/visiblethread.env:
vtdocs.database.host=<db-server>
vtdocs.database.port=5432
vtdocs.database.name=visiblethread
vtdocs.database.username=visiblethread
vtdocs.database.password=<password>
Then restart it:
sudo systemctl restart visiblethread-docs
4. VTRAG
After installing the package in step 6, edit /etc/default/vtrag.env. Set VTRAG_DB_HOST to your server's address and VTRAG_DB_PASS to a new password for the VTRAG database user, as well as your embeddings model.
In /opt/vtrag/setup/provision.sh, comment out pgvector_install, db_install, db_config and java_install, and uncomment db_remote_config. Then run it:
sudo PGDATABASE=postgres /opt/vtrag/setup/provision.sh
Answer y to both questions, then enter the admin user and password. Check VTRAG as in step 6.
Run VTRAG on a separate server
VTRAG can run on its own RHEL 8 or RHEL 9 server, with its own PostgreSQL 16. Use the same minimum spec as VisibleThread.
On the VTRAG server:
- Install and start PostgreSQL 16. VTRAG's provisioning script does not initialise the database on RHEL, so do it first:
sudo dnf module enable -y postgresql:16 sudo dnf install -y postgresql-server postgresql-contrib sudo postgresql-setup --initdb sudo systemctl enable --now postgresql - Download, check and install the VTRAG package as in step 6, and set your embeddings model in
/etc/default/vtrag.env. - In
/opt/vtrag/setup/provision.sh, comment outdb_install. Leavepgvector_install,db_configandjava_installon. If firewalld is running, also uncommentfw_configto open port 8010. - Run
sudo /opt/vtrag/setup/provision.sh, answery, and check VTRAG as in step 6.
Allow the VisibleThread server to reach port 8010 on the VTRAG server, for example in your cloud security group. From the VisibleThread server, this should print 200:
curl -s -o /dev/null -w '%{http_code}\n' http://<vtrag-server>:8010/actuator/health
Then point VisibleThread at it. Under System Admin > Generative AI, in RAG - Collection and Document Analysis, set Endpoint to http://<vtrag-server>:8010, click Test Connection, and click Save when it reports that the endpoint answered. This section appears once Visi Chat has an LLM connected.
Troubleshooting
-
Provisioning failed: check
/var/log/vt-api-provision.logfor VTAPI and/var/log/vt-rag-provision.logfor VTRAG. -
The site does not load after the install: check
sudo systemctl status visiblethread-docs, andsudo journalctl -u visiblethread-docsif it is not running. - Tomcat will not start and fapolicyd is installed: complete step 4.
-
VTRAG will not start or indexing fails: check
/var/log/vtrag/vtrag.log. A connection or authentication error there usually means a wrong endpoint, key, deployment name or region invtrag.env.