Upgrading Swarm

The section covers upgrading Swarm to a newer release.

Swarm upgrade process:

• If you installed Swarm via a source distribution archive (tar file), see Upgrade a Swarm tarball installation for details.
• If you installed Swarm via a package, see Update a Swarm package installation for details.
• If you installed Swarm via an OVA (Swarm 2014.2 or later), see Update a Swarm package installation for details.
• If you installed Swarm via an OVA (Swarm 2014.1 or earlier), see Upgrade a Swarm OVA installation from Swarm 2014.1 or earlier for details

Upgrade a Swarm tarball installation

The following process attempts to minimize downtime, but a short period of downtime for Swarm users is unavoidable. There should be no downtime for your Helix Server. After a successful upgrade, all Swarm users are logged out.

If you are using Swarm in a production environment, we encourage you to test this upgrade process in a non-production environment first.

The steps in this section describe how to upgrade Swarm using the provided archive file. SWARM_ROOT refers to the current Swarm installation.

1. Download the new TAR file from https://www.perforce.com/downloads/helix-swarm.

2. Expand the new swarm.tgz:

   $ tar -zxf swarm.tgz
   

   The contents of swarm.tgz are expanded into a top-level folder named swarm-version, where version corresponds to the version downloaded. This directory is identified as SWARM_NEW below.

3. Move SWARM_NEW to be a peer of SWARM_ROOT:

   $ mv SWARM_NEW SWARM_ROOT/../

4. Copy the SWARM_ROOT/data/config.php file from SWARM_ROOT to SWARM_NEW:

    $ cp -p SWARM_ROOT/data/config.php SWARM_NEW/data/
   

5. Create the queue token directory:

    $  mkdir SWARM_NEW/data/queue

6. Copy the existing trigger token(s):

    $ sudo cp -pR SWARM_ROOT/data/queue/tokens SWARM_NEW/data/queue/

7. Assign correct ownership to the new Swarm's data directory:

   $ sudo chown -R www-data SWARM_NEW/data

   Note

   The www-data user above is an example of what the web server user name might be, and can vary based on distribution or customization. For example, the user is typically apache for Red Hat/Fedora/CentOS, www-data for Debian/Ubuntu, wwwrun for SuSE, _www for Mac OSX.

8. Copy the new Swarm trigger script to your Helix Core Server machine. The trigger script is SWARM_NEW/p4-bin/scripts/swarm-trigger.pl, and requires installation of Perl 5.08+ (use the latest available) on the Helix Server machine. If Swarm is using SSL, then the triggers also require the IO::Socket::SSL Perl module.

   Warning

   Do not overwrite any existing trigger script at this time. Give the script a new name, for example: swarm-trigger-new.pl

9. Configure the Swarm trigger script by creating, in the same directory on the Helix Server machine, swarm-trigger.conf. It should contain:

   # SWARM_HOST (required)
   # Hostname of your Swarm instance, with leading "http://" or "https://".
   SWARM_HOST="http://my-swarm-host"
   
   # SWARM_TOKEN (required)
   # The token used when talking to Swarm to offer some security. To obtain the
   # value, log in to Swarm as a super user and select 'About Swarm' to see the
   # token value.
   SWARM_TOKEN="MY-UUID-STYLE-TOKEN"
   
   # ADMIN_USER (optional) Do not use if the Workflow technology preview feature is enabled:
   # For enforcing reviewed changes, optionally specify the normal Perforce user
   # with admin privileges (to read keys); if not set, will use whatever Perforce
   # user is set in environment.
   ADMIN_USER=
   
   # ADMIN_TICKET_FILE (optional) Do not use if the Workflow technology preview feature is enabled:
   # For enforcing reviewed changes, optionally specify the location of the
   # p4tickets file if different from the default ($HOME/.p4tickets).
   # Ensure this user is a member of a group with an 'unlimited' or very long
   # timeout; then, manually login as this user from the Perforce server machine to
   # set the ticket.
   ADMIN_TICKET_FILE=				
   										
   # VERIFY_SSL (optional)
   # If HTTPS is being used on the Swarm web server, then this controls whether
   # the SSL certificate is validated or not. By default this is set to 1, which
   # means any SSL certificates must be valid. If the web server is using a self
   # signed certificate, then this must be set to 0.
   # set the ticket.
   VERIFY_SSL=1

   Fill in the required SWARM_HOST and SWARM_TOKEN variables with the configuration from any previous Swarm trigger script, typically swarm-trigger.pl.

   Important

   The SWARM_HOST and SWARM_TOKEN variables must be deleted if the Workflow Technology preview feature is enabled.

   Note

   Swarm 2015.4 and earlier: Swarm trigger script files were available as shell scripts in these earlier Swarm versions, typically swarm-trigger.sh.

   When upgrading to Swarm 2016.1 and later the Helix Server machine must be configured to use Perl trigger scripts because the shell trigger scripts are no longer supported and have been removed.

   Note

   If you already have a swarm-trigger.conf file, no additional configuration is required.

10. For Linux systems, ensure that the script is executable:

    $ sudo chmod +x swarm-trigger-new.pl

11. Rename the new trigger script:

    $ mv swarm-trigger-new.pl swarm-trigger.pl

    On Windows:

    C:\> ren swarm-trigger-new.pl swarm-trigger.pl

12. Update the triggers in your Helix Server.

    Important

    • The swarm.shelvedel shelve-delete trigger line was added to Swarm in version 2018.1 and later. Add the swarm.shelvedel shelve-delete trigger line to the Helix Server trigger table if it is not already present, see Update the Helix Server triggers table to run the trigger script.
    • Workflow technology preview feature disabled (default): :
      • The swarm.enforce change-submit, swarm.strict change-content, and swarm.shelvesub shelve-submit trigger lines must be commented out if workflow is disabled, see Update the Helix Server triggers table to run the trigger script.
    • Workflow technology preview feature enabled:
      • The swarm.enforce.1, swarm.enforce.2, swarm.strict.1, and swarm.strict.2 trigger lines must be commented out when workflow is enabled, see Update the Helix Server triggers table to run the trigger script.
      • The swarm.enforce change-submit, swarm.strict change-content, and swarm.shelvesub shelve-submit trigger lines were added to support workflow for Swarm 2018.2 and later. If workflow is enabled, add the swarm.enforce change-submit, swarm.strict change-content, and swarm.shelvesub shelve-submit trigger lines to the Helix Server trigger table if they are not already present, see Update the Helix Server triggers table to run the trigger script.
      • The enforce and strict trigger lines have been replaced with workflow rules in Swarm 2018.2. There are currently some limitations on the workflow rules in comparison to the enforce and strict triggers, for details see Operational options.

    1. Run the Swarm trigger script to capture (using Ctrl+C on Windows and Linux, Command+C on Mac OSX) the trigger lines that should be included in the Perforce trigger table:

       $ ./swarm-trigger.pl -o

       On Windows:

       C:\> path/to/perl swarm-trigger.pl -o

    2. As a Perforce user with super privileges, update the Perforce trigger table by running p4 triggers command and replacing any swarm.* lines with the previously captured trigger line output (using Ctrl+V on Windows and Linux, Command+V on Mac OSX).
    Important

    If you previously customized the Swarm trigger lines, perhaps to apply various Trigger options, be sure to repeat those customizations within the updated trigger lines.

13. Replace the old Swarm with the new Swarm. Downtime occurs in this step.

    $ sudo apache2ctl stop; mv SWARM_ROOT SWARM.old; mv SWARM_NEW SWARM_ROOT; sudo apache2ctl start

    Note

    If you see the following error message when you start Swarm, Swarm is using the wrong version of P4PHP. The latest version of P4PHP is included in the Swarm tarball but you must configure Swarm to use that version of P4PHP. For instructions about how to configure Swarm to use the new version of P4PHP, see PHP configuration.

    

Swarm index upgrade

If you are upgrading from Swarm 2017.2 or earlier you should run the index upgrade, this ensures that the review activity history is displayed in the correct order on the Dashboard, and Reviews list pages.

The index upgrade process can be configured to suit your Swarm system specifications. See Upgrade index for details.

Run the upgrade as an Admin user by visiting the following URL:

http://SWARM-HOST/upgrade

All done!

Update a Swarm package installation

The following process attempts to minimize downtime, but a short period of downtime for Swarm users is unavoidable. There should be no downtime for your Helix Server. After a successful upgrade, all Swarm users are logged out.

If you are using Swarm in a production environment, we encourage you to test this upgrade process in a non-production environment first.

Run one of the following:

1. For Ubuntu:

   $ sudo apt-get update
   $ sudo apt-get install helix-swarm helix-swarm-triggers helix-swarm-optional

2. For CentOS/RHEL (run this command as root):

   # yum install helix-swarm helix-swarm-triggers helix-swarm-optional

Swarm generally has several major updates each year, and may occasionally have a patch update between major updates. To determine whether a Swarm update is available, run one of the following:

1. For Ubuntu:

   $ sudo apt-get update
   $ sudo apt-get -s upgrade | grep swarm

2. For CentOS/RHEL (run this command as root):

   # yum list updates | grep swarm

Swarm index upgrade

If you are upgrading from Swarm 2017.2 or earlier you should run the index upgrade, this ensures that the review activity history is displayed in the correct order on the Dashboard, and Reviews list pages.

The index upgrade process can be configured to suit your Swarm system specifications. See Upgrade index for details.

Run the upgrade as an Admin user by visiting the following URL:

http://SWARM-HOST/upgrade

All done!

Upgrade a Swarm OVA installation from Swarm 2014.1 or earlier

The following process attempts to minimize downtime, but a short period of downtime for Swarm users is unavoidable. There should be no downtime for your Helix Server. After a successful upgrade, all Swarm users are logged out.

If you are using Swarm in a production environment, we encourage you to test this upgrade process in a non-production environment first.

1. Download the new OVA from https://www.perforce.com/downloads/helix-swarm.
2. Follow the OVA setup steps. This provides you with an upgraded Swarm and an updated web hosting environment within the OVA, which can include distribution, web server, PHP, and security updates.
Important
• The swarm.shelvedel shelve-delete trigger line was added to Swarm in version 2018.1 and later. Add the swarm.shelvedel shelve-delete trigger line to the Helix Server trigger table if it is not already present, see Update the Helix Server triggers table to run the trigger script.
• Workflow technology preview feature disabled (default): :
  • The swarm.enforce change-submit, swarm.strict change-content, and swarm.shelvesub shelve-submit trigger lines must be commented out if workflow is disabled, see Update the Helix Server triggers table to run the trigger script.
• Workflow technology preview feature enabled:
  • The swarm.enforce.1, swarm.enforce.2, swarm.strict.1, and swarm.strict.2 trigger lines must be commented out when workflow is enabled, see Update the Helix Server triggers table to run the trigger script.
  • The swarm.enforce change-submit, swarm.strict change-content, and swarm.shelvesub shelve-submit trigger lines were added to support workflow for Swarm 2018.2 and later. If workflow is enabled, add the swarm.enforce change-submit, swarm.strict change-content, and swarm.shelvesub shelve-submit trigger lines to the Helix Server trigger table if they are not already present, see Update the Helix Server triggers table to run the trigger script.
  • The enforce and strict trigger lines have been replaced with workflow rules in Swarm 2018.2. There are currently some limitations on the workflow rules in comparison to the enforce and strict triggers, for details see Operational options.

3. If you have customized the original OVA's Swarm configuration:

   1. Copy /opt/perforce/swarm/data/config.php to the same path in the new OVA.
   2. Copy all token files in /opt/perforce/swarm/data/queue/tokens/ to the same path in the new OVA.
4. Shutdown the old OVA.

Swarm index upgrade

If you are upgrading from Swarm 2017.2 or earlier you should run the index upgrade, this ensures that the review activity history is displayed in the correct order on the Dashboard, and Reviews list pages.

The index upgrade process can be configured to suit your Swarm system specifications. See Upgrade index for details.

Run the upgrade as an Admin user by visiting the following URL:

http://SWARM-HOST/upgrade

All done!