Overview

This guide will walk you through the process of installing a new instance of VT Writer.

New Features in Version 5.1.3+

VT Writer 5.1.3 introduces several important improvements:

1. Configuration Changes:

   • Configuration has been split into two separate files for better modularity

2. LLM and RAG Integration (optional):

   • New capabilities to integrate with Large Language Models (LLMs)
   • Support for Retrieval Augmented Generation (RAG) workflows, including:
     • local file upload
     • Sharepoint Online integration
   • For details on configuring and using these features, see:
     • Frequently Asked Questions: VT Writer, VTRAG, and LLM Integration
     • VT Writer LLM Configuration Guide
     • VTRAG Configuration Guide
     • VT Writer SharePoint Integration Guide

System Requirements

• Operating Systems:
  • Microsoft Windows Server 2016 or newer
  • RHEL 8 or newer
  • AmazonLinux2 or newer
  • Ubuntu 24.04 or newer
• Hardware:
  • 16GB RAM
  • At least 80GB free disk space
  • 2 CPU cores or more
• Network:
  • Internet access (for package installation)
  • Ports 80 and 443 available

Prerequisites

Before you begin, ensure that:

• You have root or sudo access to the server
• The server has internet access to download packages
• You have decided whether to use the local PostgreSQL database (default) or an external database

Quick Start

Downloads:

SEE DOWNLOAD PAGE:

Download the appropriate files for your target OS. If you're comfortable with the default configuration, you can complete the installation quickly by following these steps:

 

Windows:

For Windows, simply download and run the VT Writer installer and follow the prompts to complete the installation. For detailed information, see: How to install VT Writer on Windows

 

Linux:

1. Install the VT Writer Packages

   For RHEL/Amazon Linux:

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

   For Ubuntu:

   sudo apt install -y /path/to/visiblethread-api_[version].deb
   sudo apt install -y /path/to/visiblethread-readability_[version].deb
   

2. Run the Provisioning Script

   sudo /opt/visiblethread/setup/provision.sh
   

3. Access VT Writer

   Once the installation completes successfully, access VT Writer at:

   • http://your-server-ip/ (redirects to HTTPS)
   • https://your-server-ip/

The default installation includes:

• Local PostgreSQL 16 database
• Apache configured as a reverse proxy
• Java 17 runtime
• Self-signed SSL certificate
• Basic firewall configuration

For customized installations or to use an external database, see the detailed instructions in the following sections. 

 

Custom Installation Process

Understanding the Provisioning Script

Before running the installation, it's important to understand that the provisioning script was designed to be customizable. The script decouples the application from its dependencies, allowing for more flexible installations that can be tailored to your specific environment.

1. Review the Provisioning Script

   Take some time to review the provisioning script and understand what it does:

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

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

   • os_check: Verifies the operating system compatibility
   • app_check: Checks if VT Writer is already installed
   • db_install: Installs PostgreSQL
   • 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

2. Customize the Installation (Optional)

   You can modify the provisioning script to customize your installation:

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

   Common customizations include:

   • Using a remote database by commenting out db_install and db_config and uncommenting db_remote_config
   • Skipping firewall configuration by commenting out fw_config
   • Using a different proxy server by commenting out proxy_install and proxy_config
   • Adding additional configuration steps specific to your environment

   For example, if you want to use your existing Apache installation:

   # Comment out the Apache installation line
   # proxy_install || error_exit "Failed to install Apache"
   

Standard Installation (Local Database)

After reviewing and optionally customizing the provisioning script, proceed with the installation:

1. Install the VT Writer Package

   For RHEL/Rocky Linux/Amazon Linux:

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

   For Ubuntu:

   sudo apt install -y visiblethread-readability_[version].deb
   

2. Run the Provisioning Script

   The provisioning script will handle the installation and configuration of all required components:

   sudo /opt/visiblethread/setup/provision.sh
   

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

3. What the Script Does

   The provisioning script automates the following tasks:

   • Verifies your OS is supported
   • Checks if VT Writer is already installed
   • Installs and configures PostgreSQL 16
   • Installs and configures Apache as a reverse proxy
   • Installs Java 17 and sets it as default
   • Configures firewall rules to allow HTTP/HTTPS traffic
   • Starts the VT Writer service

4. Accessing VT Writer

   Once installation is complete, you can access VT Writer at:

   • http://your-server-ip/ (redirects to HTTPS)
   • https://your-server-ip/

   Note: The initial installation uses a self-signed SSL certificate, which will cause browser security warnings. For production use, you should replace this with a trusted certificate.

External Database Installation

If you prefer to use an external PostgreSQL 16 database instead of the local one:

1. Install the VT Writer Package (same as standard installation)

2. Configure Database Connection Information

   Before running the provisioning script, update the database connection files:

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

   Set the variables in these files with your remote database information. The script will use these values to provision your remote database. None of the user/passwords should exist yet, the script will ask you for your remote DB Admin username/password when run, then connect and bootstrap with the information from the variables.

3. Modify the Provisioning Script

   Edit the provision.sh script to use remote database configuration:

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

   Comment out the local PostgreSQL installation and configuration lines:

   # Comment these lines
   # db_install || error_exit "Failed to install PostgreSQL"
   # db_config || error_exit "Failed to configure PostgreSQL"
   
   # Uncomment this line
   db_remote_config || error_exit "Failed to configure remote PostgreSQL"
   

4. Run the Modified Provisioning Script

   sudo /opt/visiblethread/setup/provision.sh
   

   When prompted during the remote database configuration step, provide the credentials for a database user with sufficient permissions to create databases, schemas, and users.

Post-Installation

Verifying Installation

To verify that VT Writer is running properly:

1. Check the service status:

   sudo systemctl status visiblethread.service
   

2. Ensure the web interface is accessible at https://your-server-ip/

Troubleshooting

If you encounter issues during installation:

• Check Installation Logs:

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

• Service Fails to Start:

  sudo journalctl -u visiblethread.service

• Apache Issues: Check web server logs:

  # RHEL-based systems
  sudo cat /var/log/httpd/error_log
  
  # Ubuntu
  sudo cat /var/log/apache2/error.log
  

Security Considerations

• The default installation creates a self-signed SSL certificate. For production use, replace it with a trusted certificate.
• Review firewall rules to ensure only necessary ports (80, 443) are exposed.
• Consider implementing IP-based access restrictions if VT Writer should only be accessible from specific networks.

For further assistance, please contact VisibleThread Support via support@visiblethread.com.