Helix Swarm Guide (2018.3)

Runtime dependencies

In order to successfully install, configure, and deploy Swarm, the following dependencies are required:

  • A Supported operating system platforms
  • An Apache web server with mod_rewrite and mod_phpx (where x is the version of PHP you are running, for example 5 or 7). For supported versions of PHP, see PHP.

  • A supported version of PHP with the following extensions:

    • iconv
    • JSON
    • Session
    • P4PHP version 2018.2 or later
    • one of APC or Zend OPCache (for optimal performance)
    • php-mbstring (for multi-byte character strings)

    In addition, Swarm greatly benefits from the following optional extensions:

    • Imagick (used for viewing non-web safe images)
    • php-xml (for RSS feeds)

  • A supported Helix Core Server deployment, and the ability to connect to it from the system hosting Swarm.

    Note

    "Helix Server deployment" can refer to a running p4d or a proxy, replica, edge server, or commit server.

  • curl or wget (for Swarm worker operation)
  • A supported version of perl (to integrate with Helix Core Server triggers)
  • That Security-enhanced Linux (SELinux), if installed, is configured

Optional dependencies:

  • LibreOffice: Required to view office-type documents. For more information, see Optional dependencies.
  • zip: command-line archiving tool: Required to download zip archives of files and folders. For more information, see Optional dependencies.
  • Helix SAML authentication enables Swarm to authenticate with a Helix Core Server configured with Helix SAML. For more information, see Optional dependencies.

Supported operating system platforms

Because Swarm includes binary versions of P4PHP (the Perforce extension for PHP), we support Swarm on the following operating systems:

  • Linux 2.6+ Intel (x86, x86_64) with glibc 2.3.3+
  • Mac OS X 10.6+ (x86_64)

Recommended for CentOS/RHEL 6: Change the following parameters in the [Pcre] section of the /etc/php.ini file to the values shown below. This ensures that very large comments are displayed:

  • pcre.backtrack_limit = 1000000
  • pcre.recursion_limit = 10000

You may be able to get Swarm running on another platform if you build P4PHP yourself and satisfy the other runtime dependencies. Instructions on how to obtain and build P4PHP from source can be found here.

Important

P4PHP does not support threaded operation. If you compile P4PHP from source, ensure that the version of PHP you compile for is non-threaded.

Apache web server

Swarm requires Apache HTTP Server 2.2 or newer:

Swarm also requires the following Apache modules:

Important

Only the prefork MPMMulti-Processing Module, a component of the Apache web server that is responsible for binding to network ports, accepting requests, and dispatch operations to handle the request. is supported. Use of the worker or event MPMs is not supported and is likely to cause problems because P4PHP does not support threaded operation.

For more information on the prefork MPM, see:

PHP

Swarm requires PHP 5.3.3+, 5.4.x, 5.5.x, 5.6.x, or 7.0:

Important

PHP must be non-threaded because P4PHP does not support threaded operation.

Required PHP extensions

Swarm requires the following PHP extensions:

  • iconv (character encoding converter)
    https://secure.php.net/iconv

    This is typically enabled by default with most PHP distributions

  • JSON (JavaScript Object Notation)
    https://secure.php.net/json

    This is typically enabled by default with most PHP distributions, although recent distributions are making this optional.

  • Session (session handling)

    This is typically enabled by default with most PHP distributions

  • P4PHP version 2018.2 or later (the Perforce PHP Extension)

    The latest P4PHP version is included with the Swarm package, OVA and tarball installations.

    Upgrading Swarm:

    • Swarm package or OVA: the latest P4PHP version is installed automatically.
    • Swarm tarball installation: you must configure Swarm to use the version of P4PHP in the new Swarm tarball. For swarm tarball upgrade instructions, see Upgrade a Swarm tarball installation.

  • php-xml (DOM API for XML manipulation)

    Included with PHP on many operating systems, but must be manually installed on CentOS/RHEL. When not installed, the Swarm RSS feed does not work.

  • php-mbstring (multi-byte character strings)

    Included with PHP on many operating systems, but must be manually installed on CentOS/RHEL. When not installed, the Swarm's RSS feed does not work.

Recommended PHP extensions

Swarm greatly benefits from the following PHP extensions:

Building PHP from source (not recommended)

If you build PHP from source, the following dependencies are required:

  • openssl
  • mcrypt
  • zlib
  • gettext
  • curl
  • apxs (Apache extension tool)

See the source PHP documentation for details on how to include these modules in your PHP build. There is normally a --with-xxxx option that defines where the dependency is loaded from.

For example for apxs and zlib:

./configure --with-apxs2=<path_to_apxs> --with-zlib=<path_to_zlib_library>

Helix Core Server requirements

Swarm works with any supported version of the Helix Server (Standard Maintenance). The versions supported in this release of Swarm are:

  • 2017.1 at 1622573 or later
  • 2017.2 at 1622831 or later
  • 2018.1
  • 2018.2

Download Helix Server from here: https://www.perforce.com/downloads/helix-core-p4d

Helix Server automated user requirements for Swarm

Swarm requires an automated user with at least admin privileges in the Helix Core Server to enable Swarm to run against the Helix Server. This can be an existing user, or a new user created specifically to support Swarm.

Important

If your Helix Server is configured for Multi-Factor Authentication (MFA), the user account running Swarm must not use MFA.

For more information about setting up Helix Core Server, see Installing and upgrading the server in Helix Core Server Administrator Guide: Fundamentals.

Trigger dependencies

Swarm triggers are installed on the Helix Server during Swarm installation.

The Swarm triggers require perl 5.08+:
https://www.perl.org/get.html

On the Windows platform, we have tested Swarm against Strawberry Perl. There are two Perl modules that are also required which may not be part of a minimal Perl installation.

  • HTTP::Tiny is required to make calls to the Swarm server. If this is not present, then the trigger will attempt to use the command line curl program. This module is standard on Strawberry Perl on Windows, and available as a package with the version of Perl provided on CentOS 7, Ubuntu 14.04 and Ubuntu 16.04.

    • IO::Socket::SSL is required if the Swarm server is configured to use SSL and HTTP::Tiny is present. This is provided as standard by Strawberry Perl, and available on Linux.

    Warning

    If the HTTP::Tiny module is not available, for example on CentOS 6, then the triggers require the use of curl. This must be installed for the triggers to function. On CentOS 6 this can be done using the yum package installer using yum install curl if it isn't already installed.

Swarm triggers also require the following perl modules to be installed:

  • Windows:
    • JSON is required to exchange data between the browser and the server and is included by default with Strawberry Perl.
  • Ubuntu:
    • JSON is required to exchange data between the browser and the server and must be installed.
    • libjson-perl is required to manipulate JSON formatted data and must be installed.
  • CentOS/RHEL:
    • JSON is required to exchange data between the browser and the server and must be installed.
    • perl-JSON is required to manipulate JSON formatted data and must be installed.

Swarm package installation on the same machine as P4D

If Swarm is installed from a package on the same machine as P4D, the triggers require the following perl modules to be installed:

  • Ubuntu:
    • Perl 5.08+
    • libio-socket-ssl-perl is required if the Swarm server is configured to use SSL.
    • libjson-perl is required to manipulate JSON formatted data and must be installed.
  • CentOS/RHEL:
    • Perl 5.08+
    • perl-IO-Socket-SSL is required if the Swarm server is configured to use SSL.
    • perl-JSON is required to manipulate JSON formatted data and must be installed.

Worker dependencies

Swarm uses short-lived workers to process the Swarm queue, new workers are regularly spawned by a recurring task.

One of the following must be installed to ensure new workers are regularly spawned:

For more information about Swarm workers, see Set up a recurring task to spawn workers.

Supported web browsers

The following browsers are supported for use with Swarm:

  • Apple Safari, latest stable version
  • Google Chrome, latest stable version
  • Mozilla Firefox, latest stable version
  • Microsoft Edge, latest stable version
  • Microsoft Internet Explorer, latest stable version

Other web browsers might also work, including prior, development or beta builds of the above web browsers, but are not officially supported.

Note

JavaScript and cookies must be enabled in the web browser for Swarm to operate.

Optional dependencies

LibreOffice

Swarm can display previews of office-type documents when LibreOffice is installed on the Swarm server. Installation is not required, but when LibreOffice is installed Swarm automatically detects its presence.

For more information about LibreOffice, see LibreOffice.

Zip

You can download a ZIP archive of files/folders when the zip command-line tool is installed on the Swarm server.

For more information about installing and configuring Zip, see Zip archive.

Helix SAML authentication

Swarm support for Helix SAML authentication with Helix Server requires Helix Server version 2018.2 or later.

Important

To use Helix SAML with Swarm:

Security-enhanced Linux (SELinux)

Swarm supports SELinux on CentOS 7. SELinux is an advanced access control mechanism that improves security for Linux distributions.

SELinux operates in one of three modes:

  • enforcing: this mode blocks and logs any actions that do not match the defined security policy. This is the default mode for SELinux on CentOS 7.
  • permissive: this mode logs actions that do not match the defined security policy but these actions are not blocked.
  • disabled: in this mode SELinux is off, actions are not blocked and are not logged.

See SELinux on CentOS 7 configuration for details.

If you see a Swarm configuration error similar to the error shown below, SELinux has not been correctly configured for Swarm. Check you have configured SELinux on CentOS 7 correctly.

Choose the installation process

Once you have reviewed the Runtime dependencies and know that you can satisfy them, there are a number of ways to install Swarm.

Tip

Installing Swarm using Install and configure Swarm from a package ensures that all of the Swarm dependencies are installed and is the easiest way to install Swarm.

Choose one of the following installation processes:

Additional product documentation
Perforce training portal
Perforce video library
Perforce knowledge base
Perforce customer support
Email us at: manual@perforce.com