Upgrade instructions for 2013.1 to 2013.2

This section covers the steps to upgrade from Swarm's 2013.1 release to the 2013.2 release. If you are not already running Swarm, these instructions do not apply to you. See the Swarm installation instructions.

Note

The instructions below can be applied to an OVA. The OVA's SWARM_ROOT, the folder where Swarm is installed, is /opt/swarm.

However, we recommend downloading the new OVA and then following the OVA setup steps. This provides you with an upgraded Swarm plus an updated web hosting environment within the OVA, which can include distribution, web server, PHP, and security updates.

If you have customized the original OVA's Swarm configuration, copy /opt/swarm/data/config.php to the same path in the new OVA.

Copy all token files in /opt/swarm/data/queue/tokens/ to the same path in the new OVA.

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 Perforce service. 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!

P4PHP 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, upgrade P4PHP before you perform any of the upgrade steps below.

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

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

  2. Move SWARM_NEW to be a peer of SWARM_ROOT: 

    $ mv SWARM_NEW SWARM_ROOT/../

  3. Copy the data/config.php file from the old Swarm to the new Swarm: 

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

  4. If you have a Swarm license file, copy the data/swarm-license file from the old Swarm to the new Swarm: 

    $ cp -p SWARM_ROOT/data/swarm-license 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 SWARM_NEW/data

    Note

    The www 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. Upgrade JIRA configuration, if necessary.

    If you enabled the JIRA module prior to the upgrade, the configuration for JIRA needs to be upgraded. See “Enabling the JIRA module” for details.

  9. Upgrade PHP to use imagick extension.

    Swarm can use the imagick extension to provide previews for image file types that most browsers cannot normally display.

    If your web server's distribution does not provide a package for imagick (e.g. php5-imagick for Debian/Ubuntu), you may be able to install imagick via PECL (once you have the ImageMagick library installed).

  10. Install LibreOffice.

    Swarm can make use of LibreOffice's file transformation capabilities to provide previews of various office document types by converting them to PDF format. See “LibreOffice” for details.

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

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

All done!