Backup and Restore qTest Data

This article provides basic instruction to create and restore a backup of qTest application data and databases for On Premise environments.

Best Practices

• Create backups of both application data and databases to ensure data integrity and consistency during the restoration process.

• Store backups remotely when possible, specifically files stored for archive purposes.

• If storing a backup locally for a temporary backup, do not store the file(s) in the application paths where qTest applications are installed or currently storing data.

1. Shut Down All qTest Applications

• Windows System Service

• Linux Systemd Service

• Docker Container Service

2. Backup Application Data and Databases (Windows and Linux only)

• qTest Manager File Backup

• qTest Sessions File Backup

• qTest Insights File Backup

• (Optional) qTest Full Application Path Backup

3. qTest File and Database Backup

• Windows and Linux

• Docker

4. Restore Application Data and Databases

• Windows and Linux

• Docker

5. qTest Database Restore (Windows and Linux only)

6. Restart qTest Applications and Verify Functionality

• Windows Service

• Linux Systemd Service

• Docker Container Service

1. Shut Down All qTest Applications

Stop all applications before performing a backup.

• Windows System Service

  On each server where qTest applications are installed:

  • Open the Services dialog and stop the “qtest” system service.

    OR

  • Execute `net stop “qtest”` from the command line.

• Linux Systemd Service

  On each server where qTest applications are installed:

  • Execute `systemctl stop qtest` (as root).

    OR

  • Execute `sudo systemctl stop qtest` (as non-root).

• Docker Container Service

  On each server where qTest applications are installed:

  • Execute `systemctl stop qtest`.

    OR

  • Execute ‘/path/to/qtest/shutdown`.

2. Backup Application Data and Databases (Windows and Linux only)

• qTest Manager File Backup

  1. Locate the configured storage location for attachments/files by viewing the qtest.config file.

     Example

     external {   manager {     data = '[path to directory where data files are stored]'   } }

  2. Copy the entire contents of this location to a backup directory (or remote directory).

     These files can be compressed using any standard Linux or Windows compression method, provided it can be uncompressed during restoration.

• qTest Sessions File Backup

  • Locate the configured storage location for attachments/files by viewing the qtest.config file.

    Example

    sessions { storage { // value must be in ['amazon_s3', 'disk_storage'] // * amazon_s3: stores resource files on amazon ec2 // * disk_storage: stores resource files on local disk type = 'disk_storage' ... rootpath = '/absolute/path/to/sessions/resources' } ... }

    Local Storage

    • Copy the entire contents of this location to a backup directory (or remote directory).

      These files can be compressed using any standard Linux or Windows compression method, provided it can be uncompressed during restoration.

    Amazon S3 Storage

    • If this file has a configuration for Amazon S3 storage, refer to the AWS technical reference for further instructions.

• qTest Insights File Backup

  • Copy the entire contents of these locations to a backup directory (or remote directory). These files can be compressed using any standard Linux or Windows compression method, provided it can be uncompressed during restoration:

    • /qtestctl/insights/build/tomcat/webapps/ROOT/CustomReports

    • /qtestctl/insights/build/tomcat/webapps/ROOT/SavedBookmarks

    • /qtestctl/insights/build/tomcat/webapps/ROOT/SavedDashboards

  • The location for Insights application data is configurable in the qtestctl installation script. The default is Function.AppPhysicalPath. Please note the configured location before creating a backup

• (Optional) qTest Full Application Path Backup

  A complete application path backup option is available in circumstances where a full backup is more efficient, where storage space is less of a concern, or in cases where there are custom configurations that should be retained.

  • Copy the entire contents of the qTest application location(s) to a backup directory (or remote directory).

    These files can be compressed using any standard Linux or Windows compression method, provided it can be uncompressed during restoration.

    Be aware of full and relative paths when compressing the entire directory tree.

3. qTest File and Database Backup

Windows and Linux

Database Backup Best Practices

• Check database size prior to initiating a backup.

  Example

  `sudo -u postgres psql -c “select pg_size_pretty(pg_database_size('<database_name>'))”`

  OR

  From PSQL interactive shell:

  # select pg_size_pretty(pg_database_size('<database_name>'));

• Check available disk space prior to beginning a database backup.

• Estimate 150% of current database size for required storage for each database.

• Remote storage is highly recommended for this process.

• For simplicity, pg_dump may be used for a simple backup for a single database.

  Example

  `pg_dump -h <IP/FQDN of DB Server> -p <PGSQL Port> -U <PGSQL Superuser> -d <Database Name>` > /location/of/backup/file/<databasename>.<date>.sql`

• Depending on security and user configuration, a database superuser password may be required.

• When in doubt, refer to PostgreSQL documentation for detailed backup process guidance.

qTest File and Database Backup

1. Locate the database server name, username, and database name from the qtest.config file.

   Example

   external {    postgres {    host = '[IP or hostname of PostgreSQL server]'  port = [PostgreSQL server port number] }    auth {  user = '[PostgreSQL username]'  pass = '[PostgreSQL user password]'  }  db {    qTest = '[Database name of qTest Manager]'    sessions = '[Database name of qTest Sessions]'   }

   There are four separate databases (database names may vary): Manager, Sessions, Parameters, and Pulse. These databases can be backed up separately or as a full PostgreSQL cluster.

2. Execute a database (or cluster) backup using one of the methods prescribed by PostgreSQL documentation.

   • For version 9.6: https://www.postgresql.org/docs/9.6/backup.html

   • For version 10 - https://www.postgresql.org/docs/10/backup.html

Docker

Database Backup Best Practices

• Review backup file size before initiating restore.

• Review available disk space on the server there the database will be restored.

• Ensure that the target database exists on the server prior to attempting a restore.

• Ensure that the database names are identical between the existing database and the information in the backup file.

• For simplicity, a simple psql redirect may be used to restore a database from backup.

  Example

  `psql [database_name] < /location/of/backup/file/[databasename].[date].sql`

• Depending on security and user configuration, a database superuser password may be required.

• When in doubt, refer to PostgreSQL documentation for detailed backup process guidance.

qTest File and Database Backup

• Execute the provided backup shell script on each qTest server running Docker.

  The script is present in the directory where qTest is installed.

  Example

  # bash /path/to/qtest/backup

  # chmod +x /path/to/qtest/backup && /path/to/qtest/backup

  # cd /path/to/qtest && chmod +x backup && ./backup

  This script will create a backup file in a pre-configured location within the container with a naming convention of `yyyy-mm-dd.tar.gz`.

  This script has the ability to store a copy of the backup file on the OS outside of the Docker container. This argument will copy the backup file to your current working directory.

  Example

  # bash /path/to/qtest/backup pull

  # chmod +x /path/to/qtest/backup && /path/to/qtest/backup pull

  # cd /path/to/qtest && chmod +x backup && ./backup pull

4. Restore Application Data and Databases

Windows and Linux

• qTest Manager File Restore

  1. Locate the configured storage location for attachments/files by viewing the qtest.config file.

     Example

     external {   manager {     data = '[path to directory where data files are stored]'   } }

  2. Move the entire contents of the previously created backup into the configured local directory.

     If the backup files were compressed, they should be uncompressed prior to moving the files into the local directory.

• qTest Sessions File Restore

  • Locate the configured storage location for attachments/files by viewing the qtest.config file.

    Example

    sessions { storage { // value must be in ['amazon_s3', 'disk_storage'] // * amazon_s3: stores resource files on amazon ec2 // * disk_storage: stores resource files on local disk type = 'disk_storage' ... rootpath = '/absolute/path/to/sessions/resources' } ... }

    Local Storage

    • Move the entire contents of the previously created backup into the configured local directory.

      If the backup files were compressed, they should be uncompressed prior to moving the files into the local directory.

    Amazon S3 Storage

    • If this file has a configuration for Amazon S3 storage, refer to the AWS technical reference for further restoration instructions.

• qTest Insights File Restore

  1. Move the entire contents of the previously created backup into the configured local directory.

     If the backup files were compressed, they should be uncompressed prior to moving the files into the local directory.

  2. Verify the local paths exist and restore the following data:

     • /qtestctl/insights/build/tomcat/webapps/ROOT/CustomReports

     • /qtestctl/insights/build/tomcat/webapps/ROOT/SavedBookmarks

     • /qtestctl/insights/build/tomcat/webapps/ROOT/SavedDashboards

     Before restoring data, please note the configured location for Insights files as it may have been changed from the default

• (Optional) qTest Full Application Path Restore

  A complete application path restore option is available in circumstances where a full backup is more efficient, where storage space is less of a concern, or where applications are being moved to a new physical server or virtual machine.

  This method may not be appropriate for restoration of data following any qTest upgrade, as restoring the entire directory tree will overwrite required files for the new qTest version. If there are customized configurations in the full path backup, use caution in copying them into the directory tree for the new qTest version.

  1. In non-upgrade situations, locate the full path backup and copy the contents to the location of the qTest applications in the directory tree.

     This method may require that large numbers of files be overwritten in the target location. Be aware of the contents before confirming overwrite, as well as full and relative paths when uncompressing the entire directory tree.

  2. Before starting any qTest application, review the qtest.config file and ensure that all configuration data (such as URLs, file storage locations, host names, and TLS certificate locations) are still accurate.

Docker

• Execute the provided restore shell script on each qTest server running Docker.

  The script is present in the directory where qTest is installed.

  Example

  # bash /path/to/qtest/restore

  # chmod +x /path/to/qtest/restore && /path/to/qtest/restore

  # cd /path/to/qtest && chmod +x backup && ./restore

  This script will create a backup file in a pre-configured location within the container with a naming convention of `yyyy-mm-dd.tar.gz`.

  This script has the ability to restore from any existing backup file using a date argument. If no argument is provided, the most recent backup will be restored.

  Example

  # bash /path/to/qtest/restore [yyyy-mm-dd]

  # chmod +x /path/to/qtest/restore && /path/to/qtest/restore [yyyy-mm-dd]

  # cd /path/to/qtest && chmod +x backup && ./backup restore [yyyy-mm-dd]

  # bash /path/to/qtest/restore [/path/of/backup/yyyy-mm-dd]

  # chmod +x /path/to/qtest/restore && /path/to/qtest/restore [/path/of/backup/yyyy-mm-dd]

  # cd /path/to/qtest && chmod +x backup && ./backup restore [/path/of/backup/yyyy-mm-dd]

5. qTest Database Restore (Windows and Linux only)

1. Locate the database server name, username, and database name from the qtest.config file.

   Example

   external {    postgres {    host = '[IP or hostname of PostgreSQL server]'  port = [PostgreSQL server port number] }    auth {  user = '[PostgreSQL username]'  pass = '[PostgreSQL user password]'  }  db {    qTest = '[Database name of qTest Manager]'    sessions = '[Database name of qTest Sessions]'   }

   There are four separate databases (database names may vary): Manager, Sessions, Parameters, and Pulse. These databases can be restored separately or as a full PostgreSQL cluster.

2. Execute a database (or cluster) restore using one of the methods prescribed by PostgreSQL documentation.

   • For version 9.6: https://www.postgresql.org/docs/9.6/backup.html

   • For version 10 - https://www.postgresql.org/docs/10/backup.html

6. Restart qTest Applications and Verify Functionality

After restoration, restart all qTest applications and verify proper functionality.

• Windows Service

  On each server where qTest applications are installed:

  • Open the Services dialog and start the “qtest” system service.

    OR

  • Execute `net start “qtest”` from the command line.

• Linux Systemd Service

  On each server where qTest applications are installed:

  • Execute `systemctl start qtest` (as root).

    OR

  • Execute `sudo systemctl start qtest` (as non-root).

• Docker Container Service

  On each server where qTest applications are installed:

  • Execute `systemctl start qtest`.

    OR

  • Execute ‘/path/to/qtest/qtestctl start`.