Runtime dependencies

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

  • a supported operating system platform

  • an Apache web server with mod_rewrite and mod_php5

  • A supported version of PHP with the following extensions:

    • iconv

    • JSON

    • Session

    • P4PHP

    • one of APC or Zend OPCache (for optimal performance)

    • php-mbstring (for multi-byte character strings)

    Swarm greatly benefits from the following optional extensions:

    • Imagick (used for viewing non-web safe images)

    • php-xml (for RSS feeds)

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

    Note

    A "Helix Versioning Engine 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 Versioning Engine triggers)

  • that SELinux, if installed, is disabled

Optional dependencies:

  • LibreOffice (for viewing office-type documents)

  • zip, the command-line archiving tool (for downloading archives of files/folders.

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)

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 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 MPM 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:

https://httpd.apache.org/docs/2.2/mod/prefork.html
https://httpd.apache.org/docs/2.4/mod/prefork.html

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.

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 (the Perforce PHP Extension)

    Included with the Swarm package. See the install directions.

  • 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, Swarm's 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, Swarm's RSS feed does not work.

Swarm greatly benefits from the following PHP extensions:

Perforce Server requirements

Swarm works with any supported version of the Helix Versioning Engine. The versions supported in this release of Swarm include the following versions:

  • 2015.2

  • 2016.1

  • 2016.2

  • 2017.1

Swarm performs best with the Helix Versioning Engine version 2016.2 or newer.

Swarm requires a user with at least admin privileges in the Helix Versioning Engine. This can be an existing user, or a new user created specifically to support Swarm.

Tip

For more information about how to set up a Helix Versioning Engine, see:


https://www.perforce.com/perforce/doc.current/manuals/p4sag/index.html

Trigger dependencies

The Swarm triggers, which are installed on the Helix Versioning Engine in a later step, requires:

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.

Worker dependencies

The recurring task to invoke Swarm workers, installed in a later step, requires either of:

  • curl
    https://curl.haxx.se/download.html

    Note

    For Windows, curl.exe depends on MSVCR100.dll. You can get a copy by installing the Microsoft Visual C++ Redistributable Package, available for:

    If you install Swarm with HTTPS, curl.exe requires recent CA certificates (or HTTPS connections silently fail). You can get a copy of the cacert.pem from:

    https://curl.haxx.se/docs/caextract.html

    Once downloaded, copy cacert.pem to the same folder where you installed curl.exe, and rename it to curl-ca-bundle.crt.

    Warning

    If curl (or curl.exe on Windows) cannot execute as expected, trigger execution may block or fail. For example, if MSVCR100.dll is missing from a Windows system, invoking curl.exe causes a dialog to appear.

    Prior to configuring the triggers, verify that curl executes. On Linux systems, run: 

    $ curl -h

    On Windows systems, run: 

    C:\> curl.exe -h

    The start of the output should be similar to: 

    Usage: curl [options...] <url>
Options: (H) means HTTP/HTTPS only, (F) means FTP only
     --anyauth       Pick "any" authentication method (H)
 -a, --append        Append to target file when uploading (F/SFTP)
     --basic         Use HTTP Basic Authentication (H)
     --cacert FILE   CA certificate to verify peer against (SSL)
     --capath DIR    CA directory to verify peer against (SSL)

...[truncated for brevity]...

    For a more thorough test that actually fetches content over a network, try the following test:

    • For Linux systems, run: 

      $ curl https://www.perforce.com/

    • For Windows systems, run: 

      C:\> curl.exe https://www.perforce.com/

    The output should look like HTML.

  • wget
    https://ftp.gnu.org/gnu/wget/
    http://gnuwin32.sourceforge.net/packages/wget.htm (for Windows)

Note

If you are using Powershell on Windows systems, be aware that Powershell includes aliases for curl and wget that call the Powershell command Invoke-WebRequest instead of curl.exe or wget.exe. Invoke-WebRequest has different command-line options than either curl or wget, which can be confusing.

If you want to remove the built-in aliases for curl and wget from Powershell, follow these steps:

  1. Create a Powershell profile (only if you have not already done so). 

    PS C:\> New-Item $profile -force -itemtype file

  2. Edit your profile: 

    PS C:\> notepad $profile

  3. Add the following line to your profile: 

    remove-item alias:curl
remove-item alias:wget

  4. Save the profile, and close notepad.

  5. Reload your profile. 

    PS C:\> . $profile

Supported web browsers

The following browsers are supported for use with Swarm:

  • Apple Safari, latest stable version

  • Google Chrome, latest stable version

  • Microsoft Internet Explorer 10+

  • Mozilla Firefox, 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.

Swarm requires that JavaScript and cookies are enabled in the web browser.

Optional dependencies

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

For more information, see LibreOffice.

To use the Download .zip feature (see Downloading files as ZIP archive), Swarm requires that the zip command-line tool is available.

For more information, see Archives configuration.

Security-enhanced Linux (SELinux)

Swarm is currently not supported with SELinux. We hope to support SELinux in a future release and provide guidance on the required configuration.

This version of Swarm does not work with SELinux with its default configuration in enforcing mode. If you are running a system with SELinux, Swarm may work if you set it to permissive mode with the command: 

$ sudo setenforce 0

If you do attempt to run Swarm with SELinux enabled, the following error message may appear in the Swarm log: 

2016-06-13T18:00:39-07:00 CRIT (2): exception 
'P4\Connection\Exception\ConnectException' with message 'Connect failed: 
[P4.connect()] Connect to server failed; check $P4PORT.

In this situation, SELinux may be preventing Swarm, which is running in a web server process, from connecting to your Helix Versioning Engine.

Choose installation approach

Once you are aware of Swarm's dependencies and can satisfy them, you have three choices for installing Swarm. Choose one approach:

  1. Use the Swarm packages (RPM or Debian):

  2. Use the Swarm OVA (Open Virtualization Appliance):

  3. Use the Swarm source distribution archive:

If you have not already done so, download Swarm: Download Swarm