Swarm packages // Swarm 2017.2 Guide

Swarm packages

Helix Swarm is available in two distribution package formats: Debian (.deb) for Ubuntu systems, and RPM (.rpm) for CentOS and RedHat Enterprise Linux (RHEL).

Using distribution packages greatly simplifies the installation, updating, and removal of software, as the tools that manage these packages are aware of the dependencies for each package.

Note

The Swarm packages have been thoroughly tested on Ubuntu 14.04 LTS and Ubuntu 16.04 LTS, and CentOS/RHEL 6.1-6.7, and CentOS/RHEL 7. While the packages should work on other compatible distributions, these have not been tested.

Note

A Helix Versioning Engine can refer to a Helix server (p4d), proxy, broker, replica, edge server, or commit server. It does not refer to a service user; service users are used to coordinate replication in a Helix Versioning Engine. For simplicity, the term Helix server is used to refer to any configuration of a Helix Versioning Engine.

Installation

Configure the Perforce package repository, on the server to host Swarm and on the server hosting your Helix Versioning Engine.

Important

If the server hosting your Helix Versioning Engine cannot use packages, for example when it is running Windows, skip this step on that server.

As root, run one of the following:
1. For Ubuntu 14.04:
  
  Create the file /etc/apt/sources.list.d/perforce.list with the following content:
```
deb http://package.perforce.com/apt/ubuntu/ trusty release
```
2. For Ubuntu 16.04:
  
  Create the file /etc/apt/sources.list.d/perforce.list with the following content:
```
deb http://package.perforce.com/apt/ubuntu/ xenial release
```
3. For CentOS/RHEL 6:
  
  Create the file /etc/yum.repos.d/helix-swarm.repo with the following content:
```
[Perforce]
name=Perforce
baseurl=http://package.perforce.com/yum/rhel/6/x86_64/
enabled=1
gpgcheck=1
```
4. For CentOS/RHEL 7:
  
  Create the file /etc/yum.repos.d/helix-swarm.repo with the following content:
```
[Perforce]
name=Perforce
baseurl=http://package.perforce.com/yum/rhel/7/x86_64/
enabled=1
gpgcheck=1
```
Import the Perforce package signing key, on the server to host Swarm and the server hosting your Helix Versioning Engine.

Important

If the server hosting your Helix Versioning Engine cannot use packages, for example when it is running Windows, skip this step on that server.

Run one of the following:
1. For Ubuntu:
```
$ wget -qO - https://package.perforce.com/perforce.pubkey | sudo apt-key add -
$ sudo apt-get update
```
2. For CentOS/RHEL (run this command as root):
```
# rpm --import https://package.perforce.com/perforce.pubkey
```
For information about how to verify the authenticity of the signing key, see: https://www.perforce.com/perforce-packages
Install the main Swarm package on the server to host Swarm.

Run one of the following:
1. For Ubuntu:
```
$ sudo apt-get install helix-swarm
```
2. For CentOS/RHEL (run this command as root):
```
# yum install helix-swarm
```
  Note
  
  For CentOS/RHEL, the firewall configuration may need to be adjusted to allow access to the web server.
  1. For CentOS/RHEL 6.x:
    $ sudo lokkit -s http
    If you subsequently wish to enable HTTPS, run (as root):
    $ sudo lokkit -s https
  2. For CentOS/RHEL 7.x:
    $ sudo firewall-cmd --permanent --add-service=http $ sudo systemctl reload firewalld
    If you subsequently wish to enable HTTPS, run (as root):
    $ sudo firewall-cmd --permanent --add-service=https $ sudo systemctl reload firewalld
Install the Swarm triggers package on the server hosting your Helix Versioning Engine.

Install this package on the server hosting your Helix Versioning Engine, which may be the same server that is hosting Swarm, or elsewhere on your network.

Important

If the server hosting your Helix Versioning Engine cannot use packages, for example when it is running Windows, you need to copy the appropriate Swarm trigger script from /opt/perforce/swarm/p4-bin/scripts to the server hosting your Helix Versioning Engine. The swarm-trigger.pl is for both Linux and Windows systems. Once copied, the trigger script needs to be configured. See Perforce configuration for Swarm for details.

Run one of the following:
1. For Ubuntu:
```
$ sudo apt-get install helix-swarm-triggers
```
2. For CentOS/RHEL (run this command as root):
```
# yum install helix-swarm-triggers
```
Important

The package installs a config file at /opt/perforce/etc/swarm-trigger.conf that you will need to modify. See Perforce configuration for Swarm for more details on configuring that file.
Optional: Install the Swarm optional package, on the server hosting Swarm.

While not required, installing this package installs the dependencies required to use the Imagick and LibreOffice Swarm modules. These modules provide previews of a variety of image and office documents.

Run one of the following:
1. For Ubuntu:
```
$ sudo apt-get install helix-swarm-optional
```
2. For CentOS/RHEL (run this command as root):
```
# yum install helix-swarm-optional
```
  Important
  
  This package depends on the package php-pecl-imagick which is available from the EPEL project. In order to install packages from EPEL, you will need to add the EPEL repository and accept its signing key. Instructions are available at: https://fedoraproject.org/wiki/EPEL
  
  Note
  
  Installation of this package also installs APC for CentOS/RHEL 6, or Zend OPCache for CentOS/RHEL 7.
Complete the Post-installation configuration steps.

Updating

Important

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

Run one of the following:

For Ubuntu:

$ sudo apt-get update
$ sudo apt-get install helix-swarm helix-swarm-triggers helix-swarm-optional

For CentOS/RHEL (run this command as root):

# yum install helix-swarm helix-swarm-triggers helix-swarm-optional

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:

For Ubuntu:

$ sudo apt-get update
$ sudo apt-get -s upgrade | grep swarm

For CentOS/RHEL (run this command as root):
```
# yum list updates | grep swarm
```

Uninstall

Remove the Swarm triggers from your Helix Versioning Engine.
Remove the Swarm trigger scripts from the server hosting your Helix Versioning Engine.

Important

If you manually installed the trigger script, perhaps because the server hosting your Helix Versioning Engine cannot use packages (e.g. Windows), manually remove the script. swarm-trigger.pl is for Linux systems. swarm-trigger.vbs is for Windows systems.

Run one of the following:
1. For Ubuntu:
```
$ sudo apt-get remove helix-swarm-triggers
```
2. For CentOS/RHEL (run this command as root):
```
# yum remove helix-swarm-triggers
```
Remove the Swarm packages from the server hosting Swarm.

Run one of the following:
1. For Ubuntu:
```
$ sudo apt-get remove helix-swarm
```
2. For CentOS/RHEL (run this command as root):
```
# yum remove helix-swarm
```
If you installed the optional package, remove it from the server hosting Swarm.

Run one of the following:
1. For Ubuntu:
```
$ sudo apt-get remove helix-swarm-optional
```
2. For CentOS/RHEL (run this command as root):
```
# yum remove helix-swarm-optional
```

Post-installation configuration

Once the helix-swarm package has been installed, additional configuration is required. Perform the following steps:

Use the Swarm configuration script to setup Swarm, on the server hosting Swarm.

Note

The Swarm configuration script can be used in a few different ways. The steps below outline the most straightforward configuration using an interactive install, but you can review the options by running:

$ sudo /opt/perforce/swarm/sbin/configure-swarm.sh -h

Run an interactive install:

$ sudo /opt/perforce/swarm/sbin/configure-swarm.sh

The configuration script displays the following summary:

------------------------------------------------------------
configure-swarm.sh: Thu Aug 25 11:29:49 PDT 2016: commencing configuration of Swarm

Summary of arguments passed:
Interactive?       [yes]
Force?             [no]
P4PORT             [(not specified)]
Swarm user         [(not specified, will suggest swarm)]
Swarm password     [(not specified)]
Email host         [(not specified)]
Swarm host         [(not specified, will suggest myhost)]
Swarm port         [80]
Swarm base URL     [(default (empty))]
Create Swarm user? [no]
Super user         [(not specified)] * not needed
Super password     [(not specified)] * not needed

Provide information to the configuration script.

After the summary, the configuration script prompts for the following information:

Specify a value for P4PORT.
```
No P4PORT specified

Swarm requires a connection to a Helix Versioning Engine.
Please supply the P4PORT to connect to.

Helix Versioning Engine address (P4PORT):
```
Specify the hostname and port for your Helix Versioning Engine. If defined, the value for P4PORT is used as the default. The configuration script verifies that it can connect:
```
-response: [myp4host:1666]

Checking P4PORT [myp4host:1666]...
-P4 command line to use: [/opt/perforce/bin/p4 -p myp4host:1666]
Attempting connection to [myp4host:1666]...
-connection successful:
  Server address: myp4host:1666
  Server version: P4D/LINUX26X86_64/2016.1/1411799 (2016/07/12)
  Server license: 10000 users (support ends 2017/05/16) 
  Server license-ip: 192.168.0.1
```
Important

If your Helix Versioning Engine is deployed using the commit-edge architecture, ensure that Swarm's port value points to the commit server.

For more information, see "Commit-edge Architecture" in the Perforce Server Administrator's Guide: Multi-site Deployment.

Specify the userid and password of a normal user with admin-level privileges in the Helix Versioning Engine.

Checking Swarm user credentials...
No Swarm user specified

Swarm requires a Helix user account with 'admin' rights.
Please provide a username and password for this account.
If this account does not have 'admin' rights, it will
be set for this user.

Helix username for the Swarm user [swarm]:

Enter the userid. The default is swarm.

Note

If the Helix user account is given 'super' rights, then this allows a user to clean up a review created by another user when the review is committed. See Review cleanup.

-response: [swarm]

Helix password or login ticket for the Swarm user (typing hidden):

Enter the login ticket, or password, for the userid.

Note

You can obtain a login ticket by running (in another shell):

$ p4 -p myp4host:1666 -u userid login -p

If the login ticket you provide would expire in less than a year, you will receive a warning.

Checking Swarm user credentials...
-checking if user [swarm] exists in [myp4host:1666]...
-user exists
Obtaining Helix login ticket for [swarm] in [myp4host:1666]...
-login ticket obtained
Checking user [swarm]'s ticket against [myp4host:1666]...
-login ticket is good
Checking user [swarm] has at least access level [admin]...
-user has maximum access level [admin]
-user meets minimum access level [admin]

Specify the hostname for the Swarm UI.

Swarm needs a distinct hostname that users can enter into their browsers to
access Swarm. Ideally, this is a fully-qualified domain name, e.g.
'swarm.company.com', but it can be just a hostname, e.g. 'swarm'.

Whatever hostname you provide should be Swarm-specific and not shared with
any other web service on this host.

Note that the hostname you specify typically requires configuration in your
network's DNS service. If you are merely testing Swarm, you can add a
hostname->IP mapping entry to your computer's hosts configuration.

Hostname for this Swarm server [myhost]:

Note

The default is the current hostname. The configuration script does not verify that the hostname actually works (DNS configuration may not exist yet).

Specify a mail relay host.
```
Swarm requires an mail relay host to send email notifications.

Mail relay host (e.g.: mx.yourdomain.com):
```
Note

The configuration script does not verify that the mail relay host you provide actually accepts SMTP connections.

Once this information has been provided, the configuration script performs the following steps (some of the detail depends on the version of PHP and Apache that is installed):

Configuring Cron...
`/opt/perforce/etc/swarm-cron-hosts.conf.new' -> `/opt/perforce/etc/swarm-cron-hosts.conf'
-updated cron configuration file with supplied Swarm host
Configuring Swarm installation...
-composed new Swarm config file contents
`/opt/perforce/swarm/data/config.php.new' -> `/opt/perforce/swarm/data/config.php'
-wrote new Swarm config file to reflect new configuration
-identified Apache user:group: [www-data:www-data]
-setting permissions on the Swarm data directory...
-ensured file permissions are set properly
Configuring Apache...
-identified Swarm virtual host config file: [/etc/apache2/sites-available/perforce-swarm-site.conf]
-identified Apache log directory: [/var/log/apache2]
-updated the vhost file to set Apache log directory
-updated the vhost file to reflect Swarm host
-checking Apache modules...
Enabling module rewrite.
Module php5 already enabled
To activate the new configuration, you need to run:
  service apache2 restart
-proper Apache modules are enabled
-enabling Swarm Apache site...
Enabling site perforce-swarm-site.conf.
To activate the new configuration, you need to run:
  service apache2 reload
-Swarm Apache site enabled
-restarting Apache...
-Apache restarted
configure-swarm.sh: Thu Aug 25 11:31:36 PDT 2016: completed configuration of Helix Swarm

::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::
::
::  Swarm is now configured and available at:
::
::      http://myhost/
::
::  You may login as the Swarm user [swarm] using the password
::  you specified.
::
::  Please ensure you install the following package on the server
::  hosting your Helix Versioning Engine.
::
::      helix-swarm-triggers
::
::  (If your Helix Versioning Engine is hosted on an OS and
::  platform that is not compatible with the above package, you can
::  also install the trigger script manually.)
::
::  You will need to configure the triggers, as covered in the Swarm
::  documentation:
::
::  http://www.perforce.com/perforce/doc.current/manuals/swarm/setup.perforce.html
::
::  Documentation for optional post-install configuration, such as
::  configuring Swarm to use HTTPS, operate in a sub-folder, or on a
::  custom port, is available:
::
::  https://www.perforce.com/perforce/doc.current/manuals/swarm/setup.post.html
::
::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::

Note

If you have installed Swarm on a host that does not provide other web services, you may wish to disable Apache's default site configuration. Doing so means that regardless of the hostname a user might use to reach the web server hosting Swarm, Swarm would be presented.

Be aware that disabling Apache's default site configuration could disable existing web services or content.

Disabling Apache's default site configuration on Ubuntu hosts is easy. Run:

$ sudo a2dissite 000-default

For CentOS hosts, or for non-standard Apache installations, you would need to manually adjust the Apache configuration. Such changes require familiarity with Apache configuration; for more details, see: https://httpd.apache.org/docs/current/configuring.html

Configure the Swarm triggers, on the server hosting your Helix Versioning Engine.

As the script's output notes, the triggers required for Swarm need to be configured if you have not already done so. See Perforce configuration for Swarm for details.
Review the Post-install configuration options for additional configuration alternatives for your Swarm installation.

Swarm 2017.2 Guide (August 2017)

Swarm packages

Note

Note

Installation

Important

Important

Note

Important

Important

Important

Note

Updating

Important

Uninstall

Important

Post-installation configuration

Note

Important

Note

Note

Note

Note

Note