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
andmod_phpx
(wherex
is the version of PHP you are running, for example 7). For supported versions of PHP, see PHP. -
A supported version of PHP with the following extensions:
- iconv
- JSON
- Session
- P4PHP version 2019.1 or later
- php-mbstring (for multi-byte character strings)
In addition, Swarm greatly benefits from the following optional extensions:
- OPCache (recommended for optimal performance)
- 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
orwget
(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.11+
- 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.
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.4 or newer:
ImportantCentOS/RHEL only:
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.
Swarm also requires the following Apache modules:
mod_phpx
for interacting with PHP (usually installed with PHP)-
mod_rewrite
URL rewriting engine
Where x
is the version of PHP you are running, for example 7. For supported versions of PHP, see PHP.
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: https://httpd.apache.org/docs/2.4/mod/prefork.html
PHP
Swarm requires PHP 7.0, 7.1, or 7.2:
Important
- PHP must be non-threaded because P4PHP does not support threaded operation.
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.
Required PHP extensions
Swarm requires the following PHP extensions:
If you install Swarm from a package, all of these PHP extensions are automatically pulled in as dependencies on all platforms:
-
iconv (character encoding converter)
https://secure.php.net/iconvThis is typically enabled by default with most PHP distributions
-
JSON (JavaScript Object Notation)
https://secure.php.net/jsonThis 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 2019.1 or later (the Perforce PHP Extension)
The latest P4PHP version is included with the Swarm package, OVA and tarball installations.
NoteSwarm 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
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, the Swarm RSS feed will not work if not installed.)
Included with PHP on many operating systems. Must be manually installed on CentOS/RHEL unless you are installing Swarm from a package.
-
php-mbstring (multi-byte character strings, the Swarm RSS feed will not work if not installed.)
Included with PHP on many operating systems. Must be manually installed on CentOS/RHEL unless you are installing Swarm from a package.
Recommended PHP extensions
Swarm greatly benefits from the following PHP extensions:
- OPCache (recommended for optimal performance) https://secure.php.net/opcache
-
Imagick (integrates ImageMagick into PHP) https://secure.php.net/imagick
Installation instructions for Imagick.
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, zlib, and openssl:
./configure --with-apxs2=<path_to_apxs> --with-zlib=<path_to_zlib_library> --with-openssl
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
- 2019.1
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.
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 16.04, and Ubuntu 18.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.
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:
- curl, download from: https://curl.haxx.se/download.html
- wget, download from: https://ftp.gnu.org/gnu/wget/
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.
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.
To use Helix SAML with Swarm:
- Helix Server version 2018.2 or later is required.
- Write a Helix Server trigger for Helix SAML. For instructions on developing the Helix Server trigger for Helix SAML, see Triggering to use external authentication in Helix Core Server Administrator Guide: Fundamentals.
- Enable Helix SAML in Swarm with the sso_enabled configurable, see Swarm configuration.
- Configure the Swarm admin user to use ticket-based authentication, see Swarm configuration.
- Configure Swarm for Helix SAML. For instructions on how to configure Swarm for Helix SAML, see Helix SAML authentication PHP config.
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.
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:
-
Swarm packages (RPM or Debian):
- Follow the steps provided in Install and configure Swarm from a package.
- Configure the Swarm triggers on the Helix Server, see Helix Core Server configuration for Swarm.
- Review the post-install configuration options to customize your Swarm installation, see Post-install configuration options.
- You are now all set to start using Swarm. Enjoy!
TipTo get started with Swarm, see the Quickstart chapter.
-
Swarm.ova (Open Virtualization Appliance):
- Follow the steps provided in Deploy and configure a Swarm VM from an OVA.
- Configure the Swarm triggers on the Helix Server, see Helix Core Server configuration for Swarm.
- Review the post-install configuration options to customize your Swarm installation, see Post-install configuration options.
- You are now all set to start using Swarm. Enjoy!
TipTo get started with Swarm, see the Quickstart chapter.
-
Swarm.tgz (Tarball):
- Follow steps provided in the Install and configure Swarm manually from a Tarball.
- Configure Apache, see Apache configuration.
- Configure PHP, see PHP configuration.
- Configure Swarm, see Swarm configuration.
- Establish a trigger token, see Establish trigger token.
- Configure the Swarm triggers on the Helix Server, see Helix Core Server configuration for Swarm.
- Set up a recurring task to spawn workers, see Set up a recurring task to spawn workers.
- Review the post-install configuration options to customize your Swarm installation, see Post-install configuration options.
- You are now all set to start using Swarm. Enjoy!
TipTo get started with Swarm, see the Quickstart chapter.
Your search for returned result(s).