How can we help?

Search the knowledge base or browse by topic.

Follow

How to deploy VisibleThread 7 on RHEL 8 and RHEL 9

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.

Setup VT Docs Instance page with the license file chosen and the system admin details filled in

  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.

Confirmation dialog: We have created the instance. Close to login

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.

System Admin page after the first sign-in, showing Workspaces and Users and the Generative AI menu item

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:

  1. 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
    
  2. Download, check and install the VTRAG package as in step 6, and set your embeddings model in /etc/default/vtrag.env.
  3. In /opt/vtrag/setup/provision.sh, comment out db_install. Leave pgvector_install, db_config and java_install on. If firewalld is running, also uncomment fw_config to open port 8010.
  4. Run sudo /opt/vtrag/setup/provision.sh, answer y, 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.log for VTAPI and /var/log/vt-rag-provision.log for VTRAG.
  • The site does not load after the install: check sudo systemctl status visiblethread-docs, and sudo journalctl -u visiblethread-docs if 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 in vtrag.env.
Was this article helpful?
0 out of 0 found this helpful

Get Additional Help

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