This guide installs VisibleThread 7 on a single Amazon Linux 2023 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:
- An Amazon Linux 2023 server with its standard repositories.
- 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. If you do not have one, email support@visiblethread.com with your organization name and whether the server is for production or test.
Do not create a visiblethread user first. The package creates it.
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 dnf 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:
-
Remote PostgreSQL: comment out
db_installanddb_config, uncommentdb_remote_config, and set the connection details in/etc/default/vtapi.envbefore you run the script. It asks for the database admin credentials. -
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 dnf install -y ./visiblethread-docs-7.4.2-1.x86_64.rpm
The package starts the visiblethread-docs service itself.
Step 4: Check the services
sudo systemctl status vtapi
sudo systemctl status visiblethread-docs
Both should show active (running).
Step 5: Install VTRAG
VTRAG powers the AI features that search your documents. VisibleThread is already configured to use VTRAG on the same server.
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 dnf install -y ./vtrag-1.0.12-1.x86_64.rpm
The MD5 should be 15418e19c25b6900d8e491437a0e27af.
Choose your embeddings model in /etc/default/vtrag.env. The file ships set up for a local Ollama server as a placeholder. For Amazon Bedrock, VTRAG uses Titan Text Embeddings V2 (amazon.titan-embed-text-v2:0) and the server's IAM role, which needs bedrock:InvokeModel on that model. Set:
SPRING_PROFILE="bedrock"
AWS_REGION=<your-region>
The shipped file has no AWS_REGION line, so add one.
For Azure OpenAI, set SPRING_PROFILE="azure-openai" and add the Azure OpenAI block from How to Integrate an Embeddings Model for VTRAG in VisibleThread 7+.
VisibleThread already installed PostgreSQL 16 and Java 17, so turn those steps off in /opt/vtrag/setup/provision.sh by commenting out these two lines:
#db_install || error_exit "Error installing PostgreSQL."
#java_install || error_exit "Error installing Java."
Then 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. If it fails, check /var/log/vt-rag-provision.log and /var/log/vtrag/vtrag.log.
Step 6: 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.
- 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. Next, connect your LLM under System Admin > Generative AI to turn on the AI features.
Troubleshooting
-
Provisioning failed: check
/var/log/vt-api-provision.log. -
The site does not load after the install: check
sudo systemctl status visiblethread-docs, andsudo journalctl -u visiblethread-docsif it is not running.