Helix Swarm Guide (2019.1)

Upgrade Swarm

The section describes how to upgrade a Swarm package install to a newer release.

Tip

If you are not already running Swarm, none of these instructions apply to you. Instead, see the Swarm installation instructions.

Swarm upgrade process:

Upgrade a Swarm package installation

Important

For the Swarm 2015.2 release, the packages have been renamed. The following instructions upgrade your Swarm packages to the latest versions.

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.

Important
  • Swarm runtime dependencies change between releases, you must check that your system satisfies the Swarm runtime dependencies before starting the upgrade, see Runtime dependencies.
  • Review the PHP requirements before you upgrade Swarm, see PHP.

  • Review the Helix Server requirements before you upgrade Swarm, see Helix Core Server requirements.

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

  1. Run one of the following:
    • Ubuntu:

      $ sudo apt-get update
      $ sudo apt-get install helix-swarm helix-swarm-triggers helix-swarm-optional
    • CentOS/RHEL 6 (run these commands as root):

      Important
      • As part of the PHP upgrade process your Apache 2.2 server will be stopped and disabled, if you are currently using the Apache 2.2 server for any other applications they will stop working. You will either need to upgrade these applications to work with PHP 7 and Apache 2.4 or move them to another server.

      • If Apache 2.4 has been installed from the SCL packages, the Apache configuration files are installed into /opt/rh/httpd24/root/etc rather than their normal locations in /etc. This means that the usual service, systemctl, and apachectl commands will control the wrong server. To control the version of Apache used by Swarm, use one of the following:

        • For CentOS 6 to use System V scripts: service httpd24-httpd restart
        • For CentOS 7 to use systemd scripts: systemctl restart httpd24-httpd

        The apachectl command still exists, but must be run in the /opt/rh/httpd24 environment. Because of this we recommended that you use one of the above commands instead.

      • To avoid seeing the Apache HTTP server Linux test page when you start the Apache server, comment out the content of the welcome.conf file located in the /opt/rh/httpd24/root/etc/httpd/conf.d/ directory.

      The full upgrade process described below is only required the first time you upgrade to PHP 7, for future Swarm upgrades just run step b.

      The upgrade process will deploy centos-release-scl which gives Swarm access to PHP 7.x and Apache 2.4, upgrade Swarm, stop and disable the Apache 2.2 server, copy and edit Swarm files so they work with Apache 2.4, and finally start and enable the Apache 2.4 server.

      1. Deploy the centos-release-scl repository to give Swarm access to PHP 7:
      2. $ yum -y install centos-release-scl

        Tip

        If you don't deploy the centos-release-scl repository you will see an error similar to the one shown below when you do the next step:

      3. Run the Swarm upgrade, this will automatically install PHP 7.x and Apache 2.4:
      4. $ yum install helix-swarm helix-swarm helix-swarm-triggers helix-swarm-optional

      5. Disable your Apache 2.2 HTTP server so that is does not automatically start:
      6. $ chkconfig httpd off

      7. Stop your Apache 2.2 HTTP server:
      8. $ service httpd stop

      9. If you have any special php.ini configuration options set, copy the php.ini file to the /etc/opt/rh/rh-php70/php.d/ directory:
      10. $ cp /etc/php.d/php.ini /etc/opt/rh/rh-php70/php.d/php.ini

      11. Copy the perforce-swarm-site.conf file to the /opt/rh/httpd24/root/etc/httpd/conf.d/ directory:
      12. $ cp /etc/httpd/conf.d/perforce-swarm-site.conf /opt/rh/httpd24/root/etc/httpd/conf.d/perforce-swarm-site.conf

      13. Replace the /log/httpd/ filepath with /log/httpd24 in the perforce-swarm-site.conf file using the sed command:
      14. $ sed -i "s#/log/httpd/#/log/httpd24/#g" /opt/rh/httpd24/root/etc/httpd/conf.d/perforce-swarm-site.conf

      15. Update the permissions for Apache 2.4 by replacing Order allow,deny references with Require all granted in the perforce-swarm-site.conf file using the sed command:
      16. $ sed -i "s/Order allow,deny/Require all granted/g" /opt/rh/httpd24/root/etc/httpd/conf.d/perforce-swarm-site.conf

      17. Enable your Apache 2.4 HTTP server so that it automatically starts:
      18. $ chkconfig httpd24-httpd on

      19. Start the Apache 2.4 HTTP server:
      20. $ service httpd24-httpd start

    • CentOS/RHEL 7 (run these commands as root):

      Important
      • As part of the PHP upgrade process your Apache 2.2 server will be stopped and disabled, if you are currently using the Apache 2.2 server for any other applications they will stop working. You will either need to upgrade these applications to work with PHP 7 and Apache 2.4 or move them to another server.

      • If Apache 2.4 has been installed from the SCL packages, the Apache configuration files are installed into /opt/rh/httpd24/root/etc rather than their normal locations in /etc. This means that the usual service, systemctl, and apachectl commands will control the wrong server. To control the version of Apache used by Swarm, use one of the following:

        • For CentOS 6 to use System V scripts: service httpd24-httpd restart
        • For CentOS 7 to use systemd scripts: systemctl restart httpd24-httpd

        The apachectl command still exists, but must be run in the /opt/rh/httpd24 environment. Because of this we recommended that you use one of the above commands instead.

      • To avoid seeing the Apache HTTP server Linux test page when you start the Apache server, comment out the content of the welcome.conf file located in the /opt/rh/httpd24/root/etc/httpd/conf.d/ directory.

      The full upgrade process described below is only required the first time you upgrade to PHP 7, for future Swarm upgrades just run step b.

      The upgrade process will deploy centos-release-scl which gives Swarm access to PHP 7.x and Apache 2.4, upgrade Swarm, stop and disable the Apache 2.2 server, copy and edit some Swarm files so they work with Apache 2.4, and finally start and enable the Apache 2.4 server.

      1. Deploy the centos-release-scl repository to give Swarm access to PHP 7:
      2. $ yum -y install centos-release-scl

        Tip

        If you don't deploy the centos-release-scl repository you will see an error similar to the one shown below when you do the next step:

      3. Run the Swarm upgrade, this will automatically install PHP 7.x and Apache 2.4:
      4. $ yum install helix-swarm helix-swarm helix-swarm-triggers helix-swarm-optional

      5. Disable your Apache 2.2 HTTP server so that is does not automatically start:
      6. $ systemctl disable httpd

      7. Stop your Apache 2.2 HTTP server:
      8. $ systemctl stop httpd

      9. If you have any special php.ini configuration options set, copy the php.ini file to the /etc/opt/rh/rh-php71/php.d/ directory:
      10. $ cp /etc/php.d/php.ini /etc/opt/rh/rh-php71/php.d/php.ini

      11. Copy the perforce-swarm-site.conf file to the /opt/rh/httpd24/root/etc/httpd/conf.d/ directory:
      12. $ cp /etc/httpd/conf.d/perforce-swarm-site.conf /opt/rh/httpd24/root/etc/httpd/conf.d/perforce-swarm-site.conf

      13. Replace the /log/httpd/ filepath with /log/httpd24 in the perforce-swarm-site.conf file using the sed command:
      14. $ sed -i "s#/log/httpd/#/log/httpd24/#g" /opt/rh/httpd24/root/etc/httpd/conf.d/perforce-swarm-site.conf

      15. Enable your Apache 2.4 HTTP server so that it automatically starts:
      16. $ systemctl enable httpd24-httpd

      17. Start the Apache 2.4 HTTP server:
      18. $ systemctl start httpd24-httpd

      19. Check that SELinux is working correctly for your system. For instructions on configuring SELinux on CentOS 7, see SELinux on CentOS 7 configuration.
  2. 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:
    • Ubuntu:

      $ sudo apt-get update
      $ sudo apt-get -s upgrade | grep swarm
    • CentOS/RHEL (run this command as root):
      # yum list updates | grep swarm

    Important

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.

Note

If you are upgrading from Swarm version 2017.3 or later, the index upgrade step is not required.

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

Note

If you are running the Swarm 2014.2 OVA, or newer, Swarm was installed using system packages and can be upgraded by following the package update instructions.

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.

Important

Review the Helix Server requirements before you upgrade Swarm, see Helix Core Server requirements.

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.
  3. Important
  4. 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.
  5. 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.

Note

If you are upgrading from Swarm version 2017.3 or later, the index upgrade step is not required.

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 tarball installation

Note

Not recommended: The tarball instructions in this section can be applied to an OVA.

The recommended upgrade process for a Swarm OVA installation is:

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.

Warning
  • Swarm runtime dependencies change between releases, you must check that your system satisfies the Swarm runtime dependencies before starting the upgrade, see Runtime dependencies.
  • P4PHPThe PHP interface to the Helix API, which enables you to write PHP code that interacts with a Helix Server machine. should be upgraded to the version included in the new Swarm release.
    • If you have already configured PHP to use the Swarm-provided P4PHP (as recommended), this happens automatically.
    • If you have manually installed P4PHP in some other fashion, configure Swarm to use the version of P4PHP included in the new Swarm tarball before you perform any of the upgrade steps below. See PHP configuration for details.
  • Swarm package, OVA and tarball installations: 2 versions of P4PHP are supplied for each PHP 7 version supported by Swarm. They are located in the p4-bin/bin.linux26x86_64 directory.

    • perforce-php7x.so compatible with systems using SSL 1.0.2
    • perforce-php7x-ssl1.1.1.so compatible with systems using SSL 1.1.1 (by default Ubuntu 18.04 uses SSL 1.1.1)

    Where x is the version of PHP 7.

    If the perforce.ini file is not pointing at the correct version of P4PHP and you connect to an SSL enabled Helix Server:

    • The Swarm web-page will not load and you might see a Connection Reset error.
    • There might be an undefined symbol: SSLeay message in the Apache error log
  • Review the PHP requirements before you upgrade Swarm, see PHP.

  • Review the Helix Server requirements before you upgrade Swarm, see Helix Core Server requirements.

CentOS/RHEL: PHP 7.x and Apache 2.4 installation

Important
  • As part of the PHP upgrade process your Apache 2.2 server will be stopped and disabled, if you are currently using the Apache 2.2 server for any other applications they will stop working. You will either need to upgrade these applications to work with PHP 7 and Apache 2.4 or move them to another server.

  • You can use the centos-release-scl repository to install PHP 7.x and Apache 2.4, see https://wiki.centos.org/AdditionalResources/Repositories/SCL. Other repositories are available if you do not want to use the SCL repository.

  • If Apache 2.4 has been installed from the SCL packages, the Apache configuration files are installed into /opt/rh/httpd24/root/etc rather than their normal locations in /etc. This means that the usual service, systemctl, and apachectl commands will control the wrong server. To control the version of Apache used by Swarm, use one of the following:

    • For CentOS 6 to use System V scripts: service httpd24-httpd restart
    • For CentOS 7 to use systemd scripts: systemctl restart httpd24-httpd

    The apachectl command still exists, but must be run in the /opt/rh/httpd24 environment. Because of this we recommended that you use one of the above commands instead.

  • To avoid seeing the Apache HTTP server Linux test page when you start the Apache server, comment out the content of the welcome.conf file located in the /opt/rh/httpd24/root/etc/httpd/conf.d/ directory.

CentOS and RHEL do not have PHP 7 and Apache 2.4 by default so you must upgrade your system before you can upgrade Swarm. This process is only required the first time you upgrade to PHP 7.

This section describes how to install PHP 7 and Apache 2.4 on your system using the centos-release-scl repository .

  1. Deploy the centos-release-scl repository to give Swarm access to PHP 7:
  2. $ yum -y install centos-release-scl

  3. Run one of the following to install PHP 7 and migrate the Swarm Apache configuration to use Apache 2.4. This process is only required the first time you upgrade to PHP 7:
    • CentOS/RHEL 6:
      1. Install PHP and Apache:
      2. $ yum -y install rh-php70 rh-php70-php rh-php70-php-fpm httpd24

      3. Disable your Apache 2.2 HTTP server so that is does not automatically start:
      4. $ chkconfig httpd off

      5. Stop your Apache 2.2 HTTP server:
      6. $ service httpd stop

      7. Copy the perforce.ini file to /etc/opt/rh/rh-php70/php.d/ directory, this step also changes the ini filename to 30-perforce.ini. 30- is added to set the priority of the perforce.ini file.
      8. $ cp /etc/php.d/perforce.ini /etc/opt/rh/rh-php70/php.d/30-perforce.ini

      9. Replace the PHP 5.3 references with PHP 7.0 in the 30-perforce.ini file using the sed command:
      10. $ sed -i "s/53/70/g" /etc/opt/rh/rh-php70/php.d/30-perforce.ini

      11. If you have any special php.ini configuration options set, copy the php.ini file to the /etc/opt/rh/rh-php70/php.d/ directory:
      12. $ cp /etc/php.d/php.ini /etc/opt/rh/rh-php70/php.d/php.ini

      13. Copy the perforce-swarm-site.conf file to the /opt/rh/httpd24/root/etc/httpd/conf.d/ directory:
      14. $ cp /etc/httpd/conf.d/perforce-swarm-site.conf /opt/rh/httpd24/root/etc/httpd/conf.d/perforce-swarm-site.conf

      15. Replace the /log/httpd/ filepath with /log/httpd24 in the perforce-swarm-site.conf file using the sed command:
      16. $ sed -i "s#/log/httpd/#/log/httpd24/#g" /opt/rh/httpd24/root/etc/httpd/conf.d/perforce-swarm-site.conf

      17. Update the permissions for Apache 2.4 by replacing Order allow,deny references with Require all granted in the perforce-swarm-site.conf file using the sed command:
      18. $ sed -i "s/Order allow,deny/Require all granted/g" /opt/rh/httpd24/root/etc/httpd/conf.d/perforce-swarm-site.conf

      19. Enable your Apache 2.4 HTTP server so that it automatically starts:
      20. $ chkconfig httpd24-httpd on

      21. Start the Apache 2.4 HTTP server:
      22. $ service httpd24-httpd start

    • CentOS/RHEL 7:
      1. Install PHP and Apache:
      2. $ yum -y install rh-php71 rh-php71-php rh-php71-php-fpm httpd24

      3. Disable your Apache 2.2 HTTP server so that is does not automatically start:
      4. $ systemctl disable httpd

      5. Stop your Apache 2.2 HTTP server:
      6. $ systemctl stop httpd

      7. Copy the perforce.ini file to /etc/opt/rh/rh-php71/php.d/ directory, this step also changes the ini filename to 30-perforce.ini. 30- is added to set the priority of the perforce.ini file.
      8. $ cp /etc/php.d/perforce.ini /etc/opt/rh/rh-php71/php.d/30-perforce.ini

      9. Replace the PHP 5.3 references with PHP 7.1 in the 30-perforce.ini file using the sed command:
      10. $ sed -i "s/53/71/g" /etc/opt/rh/rh-php71/php.d/30-perforce.ini

      11. If you have any special php.ini configuration options set, copy the php.ini file to the /etc/opt/rh/rh-php71/php.d/ directory:
      12. $ cp /etc/php.d/php.ini /etc/opt/rh/rh-php71/php.d/php.ini

      13. Copy the perforce-swarm-site.conf file to the /opt/rh/httpd24/root/etc/httpd/conf.d/ directory:
      14. $ cp /etc/httpd/conf.d/perforce-swarm-site.conf /opt/rh/httpd24/root/etc/httpd/conf.d/perforce-swarm-site.conf

      15. Replace the /log/httpd/ filepath with /log/httpd24 in the perforce-swarm-site.conf file using the sed command:
      16. $ sed -i "s#/log/httpd/#/log/httpd24/#g" /opt/rh/httpd24/root/etc/httpd/conf.d/perforce-swarm-site.conf

      17. Enable your Apache 2.4 HTTP server so that it automatically starts:
      18. $ systemctl enable httpd24-httpd

      19. Start the Apache 2.4 HTTP server:
      20. $ systemctl start httpd24-httpd

      21. Check that SELinux is working correctly for your system. For instructions on configuring SELinux on CentOS 7, see SELinux on CentOS 7 configuration.
  4. PHP 7 and Apache 2.4 are now installed, start your Swarm upgrade, see Swarm upgrade.

Swarm upgrade

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

Tip

For OVA installations, SWARM_ROOT is /opt/perforce/swarm.

  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
    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.

    Image of the P4PHP version error message

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.

Note

If you are upgrading from Swarm version 2017.3 or later, the index upgrade step is not required.

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!