Overview

This guide will walk you through the process of installing VisibleThread RAG (VTRAG), our AI-powered retrieval and generation service. VTRAG can be installed as a standalone service or alongside your existing VT Writer installation. VTRAG requires PostgreSQL 16 with pgvector extension support.

System Requirements

• Operating Systems:
  • RHEL 8 or newer
  • Amazon Linux 2023
  • Ubuntu 24.04 or newer
  • Microsoft Windows Server 2016 or newer
• Database:
  • PostgreSQL 16 with pgvector extension
• Hardware:
  • 8GB RAM
  • At least 20GB free disk space
  • 2 CPU cores or more
• Network:
  • Internet access (for package installation)
  • Ports 80, 443, and 8010 must be available

NOTE for Windows Installs: VTRAG is bundled in the VT Writer Windows installer as an optional feature. If you wish to use VTRAG on Windows, select VTRAG when installing or upgrading and proceed with the VTRAG Configuration Guide

Prerequisites

Before you begin, ensure that:

• You have root or sudo access to the server
• PostgreSQL 16 is installed or you plan to install it during provisioning
• You have an LLM service URL to connect to VTRAG (required for operation)

Download VTRAG rpm

https://visiblethread.s3.us-east-1.amazonaws.com/public/download/vtrag-1.0.1-1.x86_64.rpm 

MD5 checksum: 05eb8eeff71f59fe1faeb5ddad657b23

Understanding Installation Options

VTRAG can be installed in two main scenarios:

1. Fresh Installation: Installing VTRAG on a clean server
2. Installation with Existing VT Writer: Installing VTRAG alongside your VT Writer installation
   • For PostgreSQL 16 environments: Simple installation
   • For PostgreSQL <16 environments: Requires database upgrade

Fresh Installation (Standalone VTRAG)

Understanding the Provisioning Script

Before running the installation, you should review the provisioning script to understand and customize your installation:

sudo cat /opt/vtrag/setup/provision.sh

The script is modular with functions that handle different aspects of the installation:

• os_check: Verifies operating system compatibility
• app_check: Checks if VTRAG is already installed
• pgvector_install: Installs the pgvector extension
• db_install: Installs PostgreSQL 16
• db_config: Configures the local database
• db_remote_config: Configures a remote database connection
• proxy_install: Installs Apache
• proxy_config: Configures Apache as a reverse proxy
• java_install: Installs Java 17
• fw_config: Configures firewall rules

Installation Steps

1. Install the VTRAG Package

   For RHEL/Amazon Linux:

   sudo yum install -y vtrag-[version].rpm
   

   For Ubuntu:

   sudo apt install -y vtrag_[version].deb
   

2. Configure VTRAG Environment

   Edit the environment file to set database and LLM service information:

   sudo nano /etc/default/vtrag.env
   

   Important variables to configure:

   VTRAG_DB_HOST=localhost     # or your external database host
   VTRAG_DB_PORT=5432
   VTRAG_DB_NAME=vtrag
   VTRAG_DB_USER=vtrag
   VTRAG_DB_PASS=yoursecurepassword
   
   # LLM service URL (required)
   VTRAG_LLM_URL=http://your-llm-service:11434/api/  # example Ollama endpoint

3. Customize Provisioning Script (Optional)

   If you're using a remote database or want to customize the installation:

   sudo nano /opt/vtrag/setup/provision.sh
   

   For external database, modify the script:

   # Comment out local database installation
   #pgvector_install || error_exit "Error installing vt-pgvector"
   #db_install || error_exit "Error installing PostgreSQL."
   #db_config || error_exit "Error configuring PostgreSQL."
   
   # Uncomment remote database configuration
   db_remote_config || error_exit "Error configuring remote PostgreSQL."
   

4. Run the Provisioning Script

   sudo /opt/vtrag/setup/provision.sh
   

   During execution, you'll be prompted to confirm that you want to proceed with the installation.

5. Verify Installation

   Check the service status:

   sudo systemctl status vtrag.service

Installing VTRAG Alongside VT Writer

For Systems with PostgreSQL 16

If your VT Writer installation already uses PostgreSQL 16, you'll need to modify the provisioning script to avoid conflicts with your existing setup:

1. Install the VTRAG Package

   sudo yum install -y vtrag-[version].rpm
   

2. Configure VTRAG Environment

   Edit the environment file to connect to your existing PostgreSQL database:

   sudo nano /etc/default/vtrag.env
   

   Set the database parameters to use your existing PostgreSQL 16 instance:

   VTRAG_DB_HOST=localhost     # or your database host
   VTRAG_DB_PORT=5432
   VTRAG_DB_NAME=vtrag
   VTRAG_DB_USER=vtrag
   VTRAG_DB_PASS=yoursecurepassword
   
   # LLM service URL (required)
   VTRAG_LLM_URL=http://your-llm-service:11434/api/    # example Ollama endpoint

3. Modify the Provisioning Script

   Since VT Writer has already installed PostgreSQL 16 and possibly Apache, you need to modify the VTRAG provisioning script to avoid reinstalling these components:

   sudo nano /opt/vtrag/setup/provision.sh
   

   Comment out the following sections to prevent conflicts with existing installations:

   # Comment out PostgreSQL installation - already done by VT Writer. Leave pgvector_install
   pgvector_install || error_exit "Error installing vt-pgvector"
   #db_install || error_exit "Error installing PostgreSQL."
   
   # Keep database configuration - this only configures the VTRAG database
   db_config || error_exit "Error configuring PostgreSQL."
   
   # If VT Writer already configured Apache, comment these out
   #proxy_install || error_exit "Error installing Apache."
   #proxy_config || error_exit "Error configuring Apache."
   
   # If Java 17 is already installed, you might want to comment this out
   #java_install || error_exit "Error installing Java."
   
   # If firewall is already configured by VT Writer, comment this out
   #fw_config || error_exit "Error configuring the firewall."
   

4. Run the Modified Provisioning Script

   sudo /opt/vtrag/setup/provision.sh
   

   This will now only install pgvector and create the VTRAG database in your existing PostgreSQL installation, then configure the VTRAG service to use it.

For Systems with PostgreSQL <16

VTRAG requires PostgreSQL 16 with the pgvector extension. If you want to install VTRAG on the same VT Writer server and you have PostgreSQL lower than v16, you will need to migrate to PostgreSQL 16 using the steps below.

If your VT Writer uses an older PostgreSQL version (10-15), you'll need to:

Back Up Your Existing Data

cd /opt/visiblethread/VisibleThreadTools
sudo ./vt-backup.sh

This creates a backup in /opt/visiblethread/VisibleThreadTools/vtbackups.

Stop Services

sudo systemctl stop visiblethread
sudo systemctl stop postgresql

Uninstall Old PostgreSQL

sudo yum remove postgresql*

# Make sure you have a good database backup!
sudo mv /var/lib/pgsql /tmp/pgsql.bak

Install Updated VT Writer and VTRAG

sudo yum install -y ./visiblethread-api-[version].rpm
sudo yum install -y ./visiblethread-readability-[version].rpm
sudo yum install -y ./vtrag-[version].rpm

Configure Environment Files

sudo nano /etc/default/visiblethread.env
sudo nano /etc/default/vtapi.env
sudo nano /etc/default/vtrag.env

 

Modify the visiblethread.env Provisioning Script

Since the previous VT Writer install has already installed Apache and setup the firewall, you need to modify the provisioning script to avoid reinstalling/reconfiguring these components:

sudo nano /opt/visiblethread/setup/provision.sh

Comment out the following sections to prevent conflicts with existing installations:

# Comment out PostgreSQL installation - already done by VT Writer.
#db_install || error_exit "Error installing PostgreSQL."

# Keep database configuration - this only configures the VTRAG database
db_config || error_exit "Error configuring PostgreSQL."

# If VT Writer already configured Apache, comment these out
#proxy_install || error_exit "Error installing Apache."
#proxy_config || error_exit "Error configuring Apache."

# If Java 17 is already installed, you might want to comment this out
#java_install || error_exit "Error installing Java."

# If firewall is already configured by VT Writer, comment this out
#fw_config || error_exit "Error configuring the firewall."

 

Run Both Provisioning Scripts

 

Now we're ready to run the VT Writer provisioner, which will reinstall and re-configure the VT Writer database. Afterwards we'll run the VTRAG provisioner, which will configure the VTRAG database.

sudo /opt/visiblethread/setup/provision.sh
sudo /opt/vtrag/setup/provision.sh

 

Restore Your Data

cd /opt/visiblethread/VisibleThreadTools
sudo ./vt-restore.sh /path/to/your/backupfile

Configuration Options

External Database Configuration

If using a remote PostgreSQL 16 database:

1. Ensure the remote database has pgvector extension installed
2. Update /etc/default/vtrag.env with remote database details
3. Modify the provisioning script to use db_remote_config
4. Run the provisioning script

Apache Proxy Configuration (Optional)

By default, VTRAG exposes its API on port 8010 locally. If you want to configure Apache to proxy this service:

1. Uncomment the proxy setup in the provisioning script:

   proxy_install || error_exit "Error installing Apache."
   proxy_config || error_exit "Error configuring Apache."
   

2. Run the provisioning script or configure Apache manually

Troubleshooting

If you encounter issues during installation:

• Check Installation Logs:

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

• Service Fails to Start:

  sudo journalctl -u vtrag.service
  

• Database Connection Issues:

  # For local database
  sudo -u postgres psql -c "SELECT 1" -d vtrag
  
  # For remote database
  PGPASSWORD=yourpassword psql -h hostname -U username -d dbname -c "SELECT 1"
  

• LLM URL Connection: Ensure your LLM service is reachable:

  curl -I your-llm-url
  

Security Considerations

• Review firewall settings to ensure appropriate access
• Consider using TLS/SSL for your LLM service connection
• The default installation creates a self-signed SSL certificate for HTTPS; consider replacing it with a trusted certificate

For further assistance, please contact VisibleThread Support.