Restoring GitCentric

This section provides information about restoring GitCentric from a backup.

Prerequisites

In order to successfully run the full_restore.sh command:

  • You must have an existing GitCentric installation to use as the target for the restore operation. This GitCentric installation can be empty.
  • <ac_home>/jre/bin must be in your system’s search path (set using the $PATH environment variable)
  • <ac_home>/postgresql/bin must be in your system’s search path (set using the $PATH environment variable)

What Gets Restored?

The full_restore.sh command restores all the files and databases in the kando_backup_site_etc_<yyyymmdd>.tar created by the full_backup.sh command. See What gets backed up? for more information.

Caution: The full_restore.sh command completely overwrites an existing GitCentric installation. If you are restoring to an existing GitCentric installation, make sure there is no data under the GitCentric home directory that needs to be saved.

Back to top

How to Restore GitCentric

To restore GitCentric:
  1. Stop the GitCentric server using shutdown.sh: 
    <ac_home>/WebUI/tomcat/bin/shutdown.sh
  2. Run full_restore.sh -l <path to gc_home> <backup.tar file>

    where

    • <path to gc_home> is the full path to the GitCentric home directory to which you want to restore.
    • <backup.tar file> is the name of the .TAR file created by full_backup.sh.

    For example: 

    ./full_restore.sh -l /home/gitcentric/AccuRevGitCentric kando_backup_site_etc_<20150213>.tar
  3. Review the full_restore.sh output and perform any required actions. For details, see Restore scenarios.
  4. Restart the Tomcat web server: 
    <ac_home>/WebUI/tomcat/bin/startup.sh

    Note: Make sure that the user starting Tomcat web server has write access to the logs, temp, webapps, and work directories in <ac_home>/WebUI/tomcat. This user should have read access to all other Tomcat web server directories and files.

Back to top

Additional steps for restoring

If your GitCentric restore was successful, you might need to perform one or more of the following tasks depending on whether or not you restored GitCentric to a new location or to a new machine. In addition, you might need to merge Gerrit configuration files.

If you restored to a new location on the same machine

If you restored GitCentric to a new location on the existing machine, you need to:

  1. Modify docBase in <ac_home>/WebUI/tomcat/conf/Catalina/<hostname>/gitcentric.xml and kandoBridge.xml to point to the new GitCentric location.
  2. Compare Gerrit configuration files in kando_backup_site_etc_<yyyymmdd>.tar and merge any changes required to support your GitCentric installation to the new ../site/etc.
  3. Restart Tomcat web server: 
    <ac_home>/WebUI/tomcat/bin/shutdown.sh
<ac_home>/WebUI/tomcat/bin/startup.sh

If you restored to a new machine

If you restored GitCentric to a new machine, you need to:

  1. Set up Tomcat web server on the new machine with:
    • <ac_home>/WebUI/tomcat/conf/Catalina/<hostname>/gitcentric.xml
    • <ac_home>/WebUI/tomcat/conf/Catalina/<hostname>/kandoBridge.xml
  2. Compare Gerrit configuration files in kando_backup_site_etc_<yyyymmdd>.tar and merge any changes required to support your GitCentric installation to the new ../site/etc.
  3. Restart Tomcat web server to adjust AccuRev settings: 
    <ac_home>/WebUI/tomcat/bin/shutdown.sh
<ac_home>/WebUI/tomcat/bin/startup.sh
  4. Use PostgreSQL psql or pgadmin tools to edit the Kando database acserver table to correct the server client path for each AccuRev Server.

If you restored to the same location

If your GitCentric restore was successful, you might need to perform one or more of the following tasks depending on whether or not you restored GitCentric to a new location or to a new machine. In addition, you might need to merge Gerrit configuration files.

If you restored to the same location, simply unpack the kando_backup_site_etc_<yyyymmdd>.tar file by running: 

tar xvf kando_backup_site_etc_<yyyymmdd>.tar

Back to top

Restore scenarios

This section describes several restore scenarios: overflow, rollback, and missing branch in the repo copy.

In typical usage, GitCentric displays a message like the following for each Git branch that is successfully restored: 

Processing branch refs/heads/master in repository /sandbox/llowry/tmp/ws/git/Repo2.git/
==============================
Branch is in sync with the GitCentric database.

When the restore is successful, no action is required on the part of the GitCentric administrator. The remainder of this section describes other scenarios that require the attention of the GitCentric administrator.

An overflow condition occurs when the GitCentric database is backed up before the Git repositories are copied. In this event, it is possible that the GitCentric database and the Git repository copies are out of synch, specifically, the GitCentric database probably does not have a complete set of AccuRev transaction-Git commit pairs reflecting the latest commits in the Git repositories.

When this happens, the GitCentric restore:

  • Identifies the latest mapped Git commit of which it is aware and resets the head there.
  • Creates a new branch that contains the commits that are not recorded in the GitCentric database. The new branch is named kando_backup_overflow_<name> where <name> is original branch name.
  • Writes a message to output like the following: 
    Processing branch refs/heads/maint in repository /sandbox/llowry/tmp/ws/git/Repo2.git/
==============================
Creating kando_backup_overflow_maint; review divergence with maint and merge as necessary.

In the case of an overflow condition, it is up to the GitCentric administrator to determine whether or not these changes need to be merged into the original branch and pushed to the Git repository. If the changes represented by the unrecorded commits are already in Git, GitCentric will automatically export them to the restored repository after you start the GitCentric server. If the missing changes are not in Git, the user can clone, then fast forward-only merge from the overflow branch to the named branch, and push.

A rollback condition can occur when there is a large interval of time between when the copy of the Git repositories was created and the GitCentric database backup was performed. In this event, the GitCentric database will have recorded Git commits which are not in the restored repositories.

When the GitCentric restore encounters a rollback condition, it writes a message to output like the following: 

Processing branch refs/heads/hotfix in repository /sandbox/llowry/tmp/ws/git/Repo1.git/
==============================
Rolling back mapped transactions that are higher than 61.

In this example, the GitCentric administrator needs to be aware that any Git transaction-Git commit pair greater than transaction number 61 is not known to the Git repositories. GitCentric has rolled back database transactions to 61, the last value known to the Git repositories. Users that have any missing changes in their clone should push them again.

If GitCentric restore cannot locate a branch, it writes a message to output like the following: 

 Processing branch refs/heads/spec in repository /sandbox/llowry/tmp/ws/git/Repo1.git/
==============================
Branch could not be found. Make sure the repository is at the expected location with the appropriate branch.

In this case, the GitCentric administrator needs to ensure that the copies of all Git repositories have been copied to their original location (that is, the location at the time the GitCentric database backup was created) and that all expected branches are present in those repositories. You may need to delete and recreate the branch mapping in GitCentric.

Back to top