Swarm 2014.3: User Guide

Configure the Perforce package repository.

As root, run one of the following:

1. For Debian:

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

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

   This works for Debian and Ubuntu systems.

2. For RPM:

   Create the file /etc/yum.repos.d/perforce-swarm.repo with the following content:

   [Perforce]
   name=Perforce
   baseurl=http://package.perforce.com/yum/rhel/6/x86_64/
   enabled=1
   gpgcheck=1
   

   This works for both RedHat and CentOS.

Import the Perforce package signing key.

Run one of the following:

1. For Debian:

   $ wget -qO - http://package.perforce.com/perforce.pubkey | sudo apt-key add -
   $ sudo apt-get update
   

2. For RPM (run this command as root):

   # rpm --import http://package.perforce.com/perforce.pubkey
   

For information about how to verify the authenticity of the signing key, see: http://answers.perforce.com/articles/KB_Article/Public-Key-for-Installation-Packages

Install the main Swarm package.

Run one of the following:

1. For Debian:

   $ sudo apt-get install perforce-swarm
   

2. For RPM (run this command as root):

   # yum install perforce-swarm
   

Install the Swarm triggers package.

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

Run one of the following:

1. For Debian:

   $ sudo apt-get install perforce-swarm-triggers
   

2. For RPM (run this command as root):

   # yum install perforce-swarm-triggers
   

Install the Swarm optional package.

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

   $ sudo apt-get install perforce-swarm-optional
   

2. For RPM (run this command as root):

   # yum install perforce-swarm-optional
   

Complete the “Post-installation configuration” steps.

For Debian:

$ sudo apt-get update

Then install the new versions of the packages you previously installed (Debian packaging does not permit a package to upgrade when its internal dependencies have changed).

$ sudo apt-get install perforce-swarm
$ sudo apt-get install perforce-swarm-triggers
$ sudo apt-get install perforce-swarm-optional

For RPM (run this command as root):

# yum update

For Debian:

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

For RPM (run this command as root):

# yum list updates | grep swarm

Remove the Swarm triggers from your Perforce service.

Remove the Swarm trigger scripts from the server hosting your Perforce service.

Run one of the following:

1. For Debian:

   $ sudo apt-get remove perforce-swarm-triggers
   

2. For RPM (run this command as root):

   # yum remove perforce-swarm-triggers
   

Remove the Swarm packages.

Run one of the following:

1. For Debian:

   $ sudo apt-get remove perforce-swarm
   

2. For RPM (run this command as root):

   # yum remove perforce-swarm
   

If you installed the optional package, remove it.

Run one of the following:

1. For Debian:

   $ sudo apt-get remove perforce-swarm-optional
   

2. For RPM (run this command as root):

   # yum remove perforce-swarm-optional
   

Use the Swarm configuration script to setup 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 Perforce service. 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/usr/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
   

2. Specify the userid and password of a user with admin-level privileges in the Perforce service.

   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/perforce-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/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
-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 perforce-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://myswarmhost/

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:

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

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.