GitSwarm 2016.3-2 Documentation

Updating GitSwarm to 2016.3

Pre-update considerations

GitSwarm can only restore backups made on the same version. Hence, a backup of GitSwarm 2015.4 can only be restored to an instance running 2015.4, and not on 2016.3 or higher versions. Although, updating GitSwarm should not result in data corruption, we recommend taking backups of your existing version before you run an update.

If you are using CentOS or RHEL, and have updated the OS distribution on your GitSwarm server from 6.x to 7.x, you need to update the URL in the Perforce repository configuration. For example, if /etc/yum.repos.d/perforce.repo contains:

baseurl=http://package.perforce.com/yum/rhel/6/x86_64

you must edit that line to read:

baseurl=http://package.perforce.com/yum/rhel/7/x86_64

After such an adjustment, we recommend that you run the following command to remove any old dependencies:

sudo yum clean all

Make sure that you login at least once to your GitSwarm installation prior to performing an update. A schema change between the 2015.4 release and the 2016.3 release might make your password invalid after updating if you have not logged in at least once.

Pre-update checks

As of GitSwarm 2016.3-2, the package installation will check the current setting for user['home'] and ensure that it is not set to a reserved directory (/opt/gitswarm, /opt/perforce or /opt/rh). If it is set to a reserved directory, the installation will fail with an error like the following:

ERROR:
ERROR: "user['home']" set to reserved directory '/opt/gitswarm'.
ERROR: '/opt/gitswarm', '/opt/perforce' and '/opt/rh' are reserved directories
ERROR: for GitSwarm and should not be used for "user['home']".
ERROR:
ERROR: Please edit:
ERROR:
ERROR:     /etc/gitswarm/gitswarm.rb
ERROR:
ERROR: update "user['home']" and ensure that it is not set to a reserved
ERROR: directory (as listed above).
ERROR: If you are upgrading your GitSwarm installation, please migrate
ERROR: your installation to the new setting for "user['home']" before
ERROR: attempting to upgrade your GitSwarm installation.  Detailed instructions
ERROR: on how to migrate your home directory can be found in our online
ERROR: documentation here:
ERROR:
ERROR:    https://www.perforce.com/perforce/doc.current/manuals/gitswarm/update/README.html#changing-gits-home-directory
ERROR:

If you are upgrading your GitSwarm instance, please follow these instructions to migrate git's home directory to a new home directory.

Update dependencies

If you have any repos mirroring their content into Helix Git Fusion, we strongly recommend that you update Helix Git Fusion and the Helix Versioning Engine prior to updating GitSwarm.

• For Ubuntu:

  sudo apt-get install helix-git-fusion-base helix-p4d

• For CentOS/RHEL:

  sudo yum install helix-git-fusion-base helix-p4d

Important: Depending on the version of the helix-p4d you may have installed previously, there may be schema/data migrations required (updating the helix-p4d package does not automatically restart the service). Schema/data migrations in the Helix Versioning Engine are typically performed by running p4d -xu. For more information, see the Upgrading p4d section in the Helix Versioning Engine Administrator Guide: Fundamentals.

Important: If you are upgrading from GitSwarm 2015.3 or prior, and you had GitLab CI enabled, you must update to GitSwarm 2015.4 before you update to GitSwarm 2016.3.

Performing the update to 2016.3

1. Download the 2016.3 GitSwarm package and install it.

   curl https://package.perforce.com/bootstrap/gitswarm.sh | sudo sh -

   The script should add the Perforce package repository, and install the latest version of GitSwarm. The update will create a backup of your existing GitSwarm data before fully installing.

2. Check the application status.

   Check if GitSwarm and its environment are configured correctly:

   sudo gitswarm-rake gitswarm:check

   If you find that GitSwarm does not seem to be operating correctly after the update, it could be that one or more GitSwarm services did not restart correctly. Should this happen, run:

   sudo gitswarm-ctl restart

Configuration Checks

As of 2016.3-2, GitSwarm will check the configured home directory and will fail its configuration phase if it's set to a reserved directory (/opt/gitswarm, /opt/perforce, /opt/rh). Setting git's home directory to a reserved directory can break git clone/pull/fetch/push operations over SSH.

If you encounter the following error when running sudo gitswarm-ctl reconfigure

Recipe: gitswarm::default
* ruby_block[Checking home directory for 'git'] action run

================================================================================
Error executing action `run` on resource 'ruby_block[Checking home directory for 'git']'
================================================================================

RuntimeError
------------
Cannot set home directory for 'git' to '/opt/gitswarm'

you must edit /etc/gitswarm/gitswarm.rb and modify the following key, changing the path to a non-reserved directory.

user['home'] = ...

Changing git's home directory

If you have an existing installation that uses a reserved directory for user['home'], please update your configuration and use the following procedure to migrate to the new home directory

1. Stop all GitSwarm services except postgresql

   sudo gitswarm-ctl stop
   sudo gitswarm-ctl start postgresql

2. Configure GitSwarm

   sudo gitswarm-ctl reconfigure

3. Rebuild git's authorized keys

   sudo gitswarm-rake gitswarm:shell:setup

   Important This command will rebuild the authorized_keys file in the 'git' user's new home directory. If this file contains anything, it must be backed up beforehand as it will be deleted and replaced with the authorized keys generated by the rake task.

4. Restart GitSwarm

   sudo gitswarm-ctl start

New configuration options

• Discovering new config options

  GitSwarm doesn't update your /etc/gitswarm/gitswarm.rb for you, but we do include an updated example template: /opt/gitswarm/etc/gitswarm.rb.template. You can see what sort of config options have been changed since last release by running:

  sudo diff /etc/gitswarm/gitswarm.rb /opt/gitswarm/etc/gitswarm.rb.template

Upgrading from GitSwarm to GitSwarm EE

Before upgrading from GitSwarm to GitSwarm EE, please ensure you have read and understand the pre-update considerations.

1. Add Perforce's repository to your package configuration.

   See this document for instructions on adding Perforce's packaging key to your keyring, as well as adding the Perforce package repository to your package configuration.

2. Update to GitSwarm EE

   1. For Ubuntu (12.04 and 14.04):

      sudo gitswarm-ctl stop
      sudo apt-get remove helix-gitswarm
      sudo apt-get clean
      sudo apt-get install helix-gitswarm-ee
      sudo gitswarm-ctl start

   2. For CentOS/RHEL (6.6+ and 7.x):

      sudo gitswarm-ctl stop
      sudo yum remove helix-gitswarm
      sudo yum clean all
      sudo yum install helix-gitswarm-ee
      sudo gitswarm-ctl start

3. Check the application status.

   Check if GitSwarm EE and its environment are configured correctly:

   sudo gitswarm-rake gitswarm:check