VisibleThread -
Help Center Find helpful articles on different VisibleThread Products


How to configure VT Docs to connect to an external database

Important Note: This guide works with VT Docs version 3.4.2 or greater.

Prerequisite: This article assumes you have PostgreSQL installed on a separate server and VT Docs is already deployed.


There are 3 main steps required to configure VT Docs to use an external Postgres database. These apply for both new installations, and migrating an existing installation to an external database.


The steps are as follows (details for each step are below)

  1. Configure the external Postgres server to all connections from your VT Docs Server
  2. Create the required VT Docs user and Schema on the Postgres server
  3. Modify the VT Docs configuration to point to the external Postgres instance


1. Allow your PostgeSQL database accept connections from the VT Docs server.

This step requires changes to the "postgres.conf" file and the "pg_hba.conf" file on your PostgreSQL server. The location of these files may depend on your Postgres installation. On Ubuntu these are located at



1.1 postgres.conf

Ensure the PostgreSQL server is listening on an address other than 'localhost', for example:

listen_addresses = '*'


1.2  pg_hba.conf

Open "pg_hba.conf" with your choice text editor and add the following line to the bottom of the file:

host      vtdocs   vtdocs    <vt-docs-server-ip/32>      md5


Save both files and restart your Postgres server for the changes to take effect.


2. Creating the VT Docs user and Schema

The first step to complete is to create the VT Docs user and database in Postgres. Once that is complete we can boostrap the database with an empty VT Docs schema (for new deployments), or we can migrate your existing data to the new database.


2.1 Creating the VT Docs database and user

Download the sql file listed below to create VT Docs user and database structure on your external PostgreSQL:




 On a system that has access to the PostgreSQL database run the file 'createDB.sql' as the postgres user.

The exact format for connecting with a psql client will depend on your system. An example is given below:


# psql -h <postgresql server name> -U postgres

postgres=> \i createDocsDB.sql

postgres=> \q 

This will create the vtdocs user in your external PostgreSQL and the VisibleThread database


2.2 Create the VT Docs Schema

There are two ways to complete this step:

  1. Create an empty VT Docs schema (for new deployments)
  2. Migrate your data from an existing VT Docs database to the new database


2.2.1 Create the empty VT Docs Schema

Download the sql file from here:


Run the attached file 'createTables.sql' as the vtdocs user (the password is 'password'). The exact format for connecting with a psql client will depend on your system. An example is listed below:

#psql -h <postgresql server name> -U vtdocs

postgres=> \i vtdocs-tables.sql

postgres=> \q


2.2.2 Migrating data from existing VT Docs deployment


Backup the local VT Docs PostgreSQL data from your existing VT Docs server:

sudo su postgres
cd /tmp/
pg_dump visiblethread > /tmp/vtdocs-backup.sql


Restore the backup file to your external database:

sudo su postgres
cd /tmp/
psql -U vtdocs -h <externaldb-IP> vtdocs < /tmp/vtdocs-backup.sql



3. Modify the VT Docs application config to point to your Database server

1. On your server that is running VT Docs, navigate to the following folder

On Ubuntu


On Red Hat



2. Open the ‘context.xml’ file for editing

Replace the line that contains “url="jdbc:postgresql://"”  with “url="jdbc:postgresql://<db server address>:5432/vtdocs"


Replace the line that contains "username="visiblethread"" with "username="vtdocs""


3. Restart the VT Docs services:


On Ubuntu:

sudo service supervisor restart


On Red Hat:

sudo service visiblethread-docs restart


Recommended config for external Postgres

We recommend that you make this change to your external postgres.conf :







Was this article helpful?
0 out of 0 found this helpful

Get Additional Help

Visit our Helpdesk for additional help and support.