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)
- Configure the external Postgres server to all connections from your VT Docs Server
- Create the required VT Docs user and Schema on the Postgres server
- 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
Ensure the PostgreSQL server is listening on an address other than 'localhost', for example:
listen_addresses = '*'
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
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:
- Create an empty VT Docs schema (for new deployments)
- 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
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
pg_dump visiblethread > /tmp/vtdocs-backup.sql
Restore the backup file to your external database:
sudo su postgres
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 Red Hat
2. Open the ‘context.xml’ file for editing
Replace the line that contains “url="jdbc:postgresql://127.0.0.1:5432/visiblethread"” 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:
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 :