Overview

This article describes how to configure VisibleThread Writer, VT RAG, and VT API to use an HTTP/HTTPS proxy for outbound connections. This is commonly required in enterprise environments where direct internet access is restricted.

Prerequisites

• VisibleThread Writer v5.2.1 or later
• Root/sudo access to the server
• Proxy server IP address and port
• Proxy server accessible from the VisibleThread server

Architecture

VisibleThread Writer consists of three main services that may require proxy configuration:

• VT Writer (Readability): Main web application
• VT API: Document processing worker
• VT RAG: AI/RAG service (optional)

Each service runs as a separate Java application and requires individual proxy configuration.

Proxy Configuration

Step 1: Verify Proxy Connectivity

Before configuring the services, verify the proxy is accessible from the server:

# Test proxy with curl
curl -x http://PROXY_IP:PROXY_PORT https://www.google.com

# Example
curl -x http://172.31.15.216:3128 https://www.google.com

If successful, proceed with service configuration.

Step 2: Configure VT Writer (Readability)

Edit the VT Writer service startup script:

sudo nano /opt/visiblethread/readability/vt_readability_service.sh

Add the proxy parameters to the java command. Locate the existing java command and add the proxy parameters:

java -Xms1G -Xmx2600m -XX:MaxMetaspaceSize=350m -Dfile.encoding=UTF-8 \
        -Dserver.use-forward-headers=true -Dspring.profiles.active=on-premise $CUSTSAMLURL \
        -Dhttp.proxyHost=PROXY_IP -Dhttp.proxyPort=PROXY_PORT \
        -Dhttps.proxyHost=PROXY_IP -Dhttps.proxyPort=PROXY_PORT \
        -Dhttp.nonProxyHosts="localhost|127.0.0.1|::1" \
        -jar /opt/visiblethread/readability/readability.jar \
        --spring.datasource.primary.max-active=400 \
        --insights.data_retrieval_interval=1800000 --insights.data_retrieval_initial_delay=5000 \
        --server.servlet.session.timeout=3600 -server.tomcat.accept-count=650 \
        --server.tomcat.max-threads=650 --server.tomcat.min-spare-threads=25

Replace PROXY_IP and PROXY_PORT with your actual proxy server details.

Example with proxy at 172.31.15.216:3128:

java -Xms1G -Xmx2600m -XX:MaxMetaspaceSize=350m -Dfile.encoding=UTF-8 \
        -Dserver.use-forward-headers=true -Dspring.profiles.active=on-premise $CUSTSAMLURL \
        -Dhttp.proxyHost=172.31.15.216 -Dhttp.proxyPort=3128 \
        -Dhttps.proxyHost=172.31.15.216 -Dhttps.proxyPort=3128 \
        -Dhttp.nonProxyHosts="localhost|127.0.0.1|::1" \
        -jar /opt/visiblethread/readability/readability.jar \
        --spring.datasource.primary.max-active=400 \
        --insights.data_retrieval_interval=1800000 --insights.data_retrieval_initial_delay=5000 \
        --server.servlet.session.timeout=3600 -server.tomcat.accept-count=650 \
        --server.tomcat.max-threads=650 --server.tomcat.min-spare-threads=25

Step 3: Configure VT API (if applicable)

Edit the VT API service startup script:

sudo nano /usr/share/vtapi/bin/vtapi

Add the proxy parameters to the java command:

java $VTAPI_JVM_MEM \
-Dhttp.proxyHost=PROXY_IP -Dhttp.proxyPort=PROXY_PORT \
-Dhttps.proxyHost=PROXY_IP -Dhttps.proxyPort=PROXY_PORT \
-Dhttp.nonProxyHosts="localhost|127.0.0.1|::1" \
-jar /usr/share/vtapi/lib/vtapi.jar

Example:

java $VTAPI_JVM_MEM \
-Dhttp.proxyHost=172.31.15.216 -Dhttp.proxyPort=3128 \
-Dhttps.proxyHost=172.31.15.216 -Dhttps.proxyPort=3128 \
-Dhttp.nonProxyHosts="localhost|127.0.0.1|::1" \
-jar /usr/share/vtapi/lib/vtapi.jar

Step 4: Configure VT RAG (if applicable)

Edit the VT RAG service startup script:

sudo nano /opt/vtrag/vt-rag-service.sh

Add the proxy parameters to the java command:

java -Xms512m "$VTRAG_JVM_MEM" \
-Dspring.profiles.active="$SPRING_PROFILE" \
-Dhttp.proxyHost=PROXY_IP -Dhttp.proxyPort=PROXY_PORT \
-Dhttps.proxyHost=PROXY_IP -Dhttps.proxyPort=PROXY_PORT \
-Dhttp.nonProxyHosts="localhost|127.0.0.1|::1" \
-jar /opt/vtrag/vtrag.jar > /var/log/vtrag/vtrag.log

Example:

java -Xms512m "$VTRAG_JVM_MEM" \
-Dspring.profiles.active="$SPRING_PROFILE" \
-Dhttp.proxyHost=172.31.15.216 -Dhttp.proxyPort=3128 \
-Dhttps.proxyHost=172.31.15.216 -Dhttps.proxyPort=3128 \
-Dhttp.nonProxyHosts="localhost|127.0.0.1|::1" \
-jar /opt/vtrag/vtrag.jar > /var/log/vtrag/vtrag.log

Step 5: Restart Services

After modifying the startup scripts, restart all affected services:

# Restart VT Writer
sudo systemctl restart vt-readability.service

# Restart VT API (if configured)
sudo systemctl restart vtapi.service

# Restart VT RAG (if configured)
sudo systemctl restart vtrag.service

# Verify services are running
sudo systemctl status vt-readability.service
sudo systemctl status vtapi.service
sudo systemctl status vtrag.service

Proxy Parameter Reference

nonProxyHosts Patterns

The http.nonProxyHosts parameter accepts wildcard patterns:

• localhost - Exact match
• 127.0.0.1 - Exact IP match
• *.example.com - Wildcard domain match
• 10.*.*.* - Wildcard IP range
• Multiple entries separated by pipe |

Example excluding internal network:

-Dhttp.nonProxyHosts="localhost|127.0.0.1|::1|10.*.*.*|*.internal.company.com"

Verification

Test External Connectivity

After configuration, verify external connectivity through the proxy:

1. Test LLM (if configured):
   • Navigate to Settings → AI Settings in VT Writer
   • Click "Test Connection"
   • Should succeed if proxy is working
2. Test SharePoint (Microsoft Graph API) if configured:
   • Navigate to Settings → Integrations → SharePoint
   • Attempt to authenticate
   • Should succeed if proxy is working
3. Check Application Logs:

# VT Writer logs
sudo tail -f /var/log/readability/readability.log

# VT API logs
sudo tail -f /var/log/vtapi/vtapi.log

# VT RAG logs
sudo tail -f /var/log/vtrag/vtrag.log

# Look for connection errors or proxy-related messages

Verify Proxy Usage

To confirm traffic is going through the proxy, check proxy logs (if available):

# Example for Squid proxy
sudo tail -f /var/log/squid/access.log

# Look for connections from the VT Writer server IP

Troubleshooting

Services Won't Start

Symptom: Service fails to start after adding proxy parameters

Resolution:

1. Check for syntax errors in the startup script
2. Verify quotes and escape characters are correct
3. Check service logs:

sudo journalctl -u vt-readability.service -n 50

Connection Still Fails

Symptom: Application still cannot connect to external services

Possible Causes:

1. Proxy authentication required: The Java proxy parameters shown do not support authenticated proxies. Contact VisibleThread Support if proxy authentication is required.
2. Proxy blocking HTTPS CONNECT: Some proxies block HTTPS tunneling. Verify proxy allows CONNECT method:

curl -v -x http://PROXY_IP:PROXY_PORT https://www.google.com

3. Firewall blocking proxy access: Verify the VT Writer server can reach the proxy:

telnet PROXY_IP PROXY_PORT
# or
nc -zv PROXY_IP PROXY_PORT

4. Application using different HTTP client: Some external integrations may not respect Java proxy settings. This is a known limitation - contact VisibleThread Support for specific integration issues.

Proxy Authentication Required

Symptom: Proxy requires username/password authentication

Resolution: The standard Java proxy parameters do not support authentication. Options:

1. Configure proxy to whitelist VT Writer server: Allow connections from the VT Writer server IP without authentication
2. Use authenticating proxy wrapper: Deploy a local proxy (like Squid) that handles authentication upstream
3. Contact VisibleThread Support: For guidance on authenticated proxy support

Internal Services Not Accessible

Symptom: After enabling proxy, cannot access internal resources (database, file shares, etc.)

Resolution: Verify nonProxyHosts includes your internal network:

-Dhttp.nonProxyHosts="localhost|127.0.0.1|::1|10.*.*.*|192.168.*.*|*.internal.domain"

Important Notes

Limitations:

• Standard Java proxy parameters do NOT support proxy authentication
• Some third-party libraries used by integrations may not respect these settings
• Proxy settings must be added to startup scripts, not environment files

Security:

• Ensure proxy server uses HTTPS if transmitting sensitive data
• Verify proxy logs are secured and access-controlled
• Review proxy ACLs to restrict access appropriately

Backup:

• Always backup startup scripts before modification
• Test changes in a non-production environment first
• Document the proxy IP/port for future reference