Swarm 2016.1 Guide (May 2016)

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

As root, run one of the following:

1. For Ubuntu 12.04:

   Create the file /etc/apt/sources.list.d/perforce.list with the following content:

   deb http://package.perforce.com/apt/ubuntu/ precise release
   

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

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.

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.

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
   

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.

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

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

Remove the Swarm triggers from your Helix Versioning Engine.

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

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
   

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

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

Run an interactive install:

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

The configuration script displays the following summary:

configure-swarm.sh: Fri Apr 18 15:00:44 PDT 2014: 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')]
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:

1. Specify a value for P4PORT.

   No P4PORT specified
   
   Swarm requires a connection to a Perforce Server.
   Please supply the P4PORT to connect your Perforce Server.
   
   Perforce Server 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/2014.1/821990 (2014/04/07)
     Server license: 10000 users (support ends 2015/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.

2. 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 Perforce user account with 'admin' rights.
   Please provide a username and password for this account.
   
   Perforce username for the Swarm user [swarm]: 
   

   Enter the userid. The default is swarm.

   -response: [swarm]
   
   Perforce 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 Perforce 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]
   

3. Specify the hostname for the Swarm UI.

   Swarm needs to set a hostname for what it will respond to in Apache;
   ensure the hostname resolves to this actual host.
   
   Hostname for this Swarm server [myhost]:
   

   Note

   The default is the current hostname. The configuration script does not verify that the hostname actually works.

4. 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 P4PHP...
-using PHP version [55]
-identified P4PHP variant: [/opt/perforce/swarm/p4-bin/bin.linux26x86_64/perforce-php55.so]
-wrote .ini file for P4PHP
Configuring Cron...
-identified Swarm cron file: [/etc/cron.d/helix-swarm]
-updated cron file to reflect Swarm host
Configuring Swarm installation...
-composed new configuration file contents
-wrote new 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/helix-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
-updated the vhost file to handle Apache 2.4 directives
-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 helix-swarm-site.
To activate the new configuration, you need to run:
  service apache2 reload
-Swarm Apache site enabled
-restarting Apache...
 * Restarting web server apache2
   ...done.
-Apache restarted
configure-swarm.sh: Fri Apr 18 15:27:23 PDT 2014: completed configuration of Perforce Swarm

Swarm is now configured and available at:

  http://myswarm.url/

You may login as the Swarm user swarm using the password you provided.

Please ensure you install the following packages on your Perforce Server host:

  helix-swarm-triggers

(If your Perforce Server host does not have an OS and platform that is 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

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.