GitSwarm-EE 2017.1-1 Documentation

Updating GitSwarm EE to 2017.1

Pre-update considerations

GitSwarm EE can only restore backups made on the same version. Hence, a backup of GitSwarm EE 2016.3 can only be restored to an instance running 2016.3, and not on 2017.1 or higher versions. Although, updating GitSwarm EE 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 EE 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 EE 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-installation checks

As of GitSwarm EE 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 EE 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 EE.

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 EE 2015.3 or prior, and you had GitLab CI enabled, you must update to GitSwarm EE 2015.4 before you update to GitSwarm EE 2017.1.

Performing the update to 2017.1

  1. Download the 2017.1 GitSwarm EE package and install it.

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

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

  2. Check the application status.

    Check if GitSwarm EE and its environment are configured correctly:

    sudo gitswarm-rake gitswarm:check

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

    sudo gitswarm-ctl restart

Configuration Checks

As of 2016.3-2, GitSwarm EE 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 EE services except postgresql

    sudo gitswarm-ctl stop
sudo gitswarm-ctl start postgresql

  2. Configure GitSwarm EE

    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 EE

    sudo gitswarm-ctl start

New configuration options