When utilizing a Load-balanced VT Docs setup, there are multiple connections to the VT Docs database. This can create issues when attempting to restore a database backup OR upgrading VT Docs to a new version. This article describes the best workflow for these two scenarios.
Restoring a Database Backup
NOTE: If you are using an AutoScaling setup in AWS (or something similar in another Cloud provider), you will want to pause that feature before moving forward.
In order to safely restore a VT Docs backup in a Load-balanced environment, you must stop the VT Docs service on all but one server. For each server you wish to stop, log in and run the following:
# RHEL8/9
sudo systemctl stop visiblethread-docs
# Ubuntu
sudo systemctl stop supervisor
# Windows
net stop vtdocs-tomcat
This will close any open database sessions for all but one of the servers; once the other servers have closed their connection, a restore operation will work as expected. Once completed, you can restart VT Docs on all servers. For each server you wish to start, log in and run the following:
# RHEL8/9
sudo systemctl start visiblethread-docs
# Ubuntu
sudo systemctl start supervisor
# Windows
net start vtdocs-tomcat
Upgrading a Load-balanced VT Docs deployment
VT Docs runs database migrations upon startup; this means that after upgrading to a new release, any database changes will occur upon starting up a new server. When there are multiple servers running, it is important to ensure that only one server tries to complete these migrations to avoid complications.
In order to safely upgrade a VT Docs deployment in a Load-balanced environment, you must stop the VT Docs service on all servers. For each server you wish to stop, log in and run the following:
# RHEL8/9
sudo systemctl stop visiblethread-docs
# Ubuntu
sudo systemctl stop supervisor
# Windows
net stop vtdocs-tomcat
Once there are no active sessions connecting to the VT Docs database, you can now upgrade each VT Docs server individually. Once this is complete, you can start the VT Docs service on one of the servers and allow it to come back up normally:
# RHEL8/9
sudo systemctl start visiblethread-docs
# Ubuntu
sudo systemctl start supervisor
# Windows
net start vtdocs-tomcat
Once you have verified that VT Docs is running on the correct version, you can start up the VT Docs service on the remaining servers (again, this should be done after each server has been upgraded). The VT Docs service will connect to the database, which has already been migrated, with no issue.