Installation of Perforce Swarm from a release package. These are environment specific instructions as provided from the INSTALL.txt found with the Swarm tar ball in the 'readme' directory. This also includes RELNOTES.txt and LICENSE.txt.
Please consider reading our thorough online documentation before proceeding.
- Ubuntu 14.04 LTS was tested.
- Curl must be installed.
- Ubuntu 10.04+ LTS is compatible. You do require PHP 5.3.3+.
- Root access (su/sudo/etc).
- Internet connection (to download required tarball package)
- familiarity with the BASH command shell
To support dynamic image resizing, and to view specific documents having the following packages is essential.
- Image Magick /w PHP5 Module
For the purposes of this installation how-to the following is assumed, so please adjust or create as necessary:
- Perforce will be installed locally. Use the correct P4PORT.
- Perforce Server is a non-Windows Server.
- Perforce Server P4ROOT will be /opt/perforce/server/
- Your Perforce Server is already running on P4PORT=1666.
- Perforce Swarm root will be /opt/perforce/swarm/
- sudo is used to gain root access, drop "sudo" if installing as root.
- That the Perforce Swarm host has a FQDN or hostname. For this example it will be https://swarm.perforce.com.
The majority of the work done to install Helix Swarm from tarball is preparing the environment. There is an INSTALL.txt document that includes more detail on environment requirements. You do NOT require a P4 Server to be installed on the same host as the Swarm server, however if you do not have a P4 Server to point Swarm to, you will have to create one and populate it with some data.
1. Install environmental requirements (Apache 2.2x+, PHP 5.3.3+, PHP Accelerated Proxy Cache).
$ sudo apt-get install apache2 php5 php-apc libreoffice imagemagick php5-imagick
2. Enable Mod_Rewrite
$ sudo a2enmod rewrite
3. Navigate to the user profile's home directory, then obtain Swarm from www.perforce.com
or from ftp.
$ cd [path to the user profile's home directory]
$ wget ftp.perforce.com/perforce/r15.1/bin.multiarch/swarm.tgz
Note: This 'wget' command will obtain the 2015.1 release. This is an example, replace "r15.1" with specific release version you want to install.
4. Extract tarball on the web-server (we will use /var/www/swarm):
$ cd [path to where swarm.tgz was downloaded]
$ sudo tar -zxvf swarm.tgz
5. Navigate to the Swarm root location, then copy extracted contents to that location:
$ cd ~/swarm-2013.1.version-number/
$ sudo cp -r . /opt/perforce/swarm/
6. In Perforce, create the admin user for swarm. This assumes P4PORT is set to 1666. Change accordingly making sure you correctly configure an email address of the human Swarm user or a Perforce Administrator:
$ p4 user -f swarm
7. Create a group for this user with a long or unlimited timeout. Remember to add the swarm user to the group:
$ p4 group swarm-group-notimeout
8. Give this group permissions in the protections table:
$ p4 protect
Above your super users add this permission line:
admin group swarm-group-notimeout * //...
9. Create a swarm user password.
$ p4 -u swarm passwd
10. Login with your swarm user to output get the ticket file.
$ p4 -u swarm login -p -a
11. Keep a record of the ticket printed. It will be a long string hash similar to this:
12. Create a config.php file in the Swarm data folder.
$ sudo vim /opt/perforce/swarm/data/config.php
The "port" is the P4PORT of the P4 Server.
'p4' => array(
'port' => '1666',
'user' => 'swarm',
'password' => 'ticket value',
13. Change the owner of the Data directory to the web service user (Ubuntu default is www-data):
$ sudo chown -R www-data:www-data /opt/perforce/swarm/data
14. Create the virtual host for the Perforce Swarm instance:
$ sudo vim /etc/apache2/sites-available/swarm.conf
Add this to the file, making note to keep the Swarm Error and Access logs under the Data directory:
CustomLog "/opt/perforce/swarm/data/swarm.access_log" common
Requite all granted
15. Create a symlink for this file to sites-enabled:
$ sudo ln -s /etc/apache2/sites-available/swarm.conf /etc/apache2/sites-enabled/
16. Ensure the P4PHP extension is in the php.ini file:
$ sudo vim /etc/php5/apache2/php.ini
add this line to the file, or around line 952 under Dynamic Extensions:
Note: You will have to select the appropriate version in the /p4-bin/ directory for both your OS architecture as well as the version of PHP. The extension above is for PHP 5.5, as configured with Ubuntu 14.04 LTS.
17. Restart the Apache server to ensure the new settings take effect, and that Apache and Swarm logs are created:
$ sudo apachectl restart
18. Create the phpinfo.php file: then visit
http://host/phpinfo.php to that the extension is loaded properly:
$ sudo vi /opt/perforce/swarm/public/phpinfo.php
And add this string:
"<?php phpinfo();?> "
Note: Verify that the PHP Apache extension is loaded properly by visiting http://swarm_host/phpinfo.php
19. Create a crontab entry that is set to spawn workers. Spaces must be between the "*" entries below.
$ sudo vi /etc/cron.d/swarm-cron
* * * * * curl -o /dev/null -m1 http://<swarm hostname>/queue/worker
Save the file.
20. Copy the trigger script to the servers local directory (Obviously, if the P4D Server is not on the host running Swarm, copy it there):
$ sudo cp /opt/perforce/swarm/p4-bin/bin.linux26x86_64/swarm-trigger.sh /opt/perforce/server
21. Change the permission of the script.
$ sudo chmod a+x /opt/perforce/server/swarm-trigger.sh
22. Determine the P4 Swarm Trigger Token.
In your browser, navigate to your Swarm host (for example, http://swarm.yourcompany.com). At this point, you should see the basic Swarm page, free of any Perforce data. If you don't see the basic Swarm page, please make sure all of the above steps have been completed successfully. Assuming you do see the basic Swarm page, do as follows:
1. In the upper right corner of the page, click "Log in"
2. Login as a super user or user with 'admin' permissions.
3. Click on the username. When the drop-down appears, click on "About Swarm"
4. Copy the 'Swarm Trigger Token' value. It will look similar to this:
23. Edit the swarm-trigger script file and change the host and configure trigger token value:
$ sudo vim /opt/perforce/server/swarm-trigger.sh
Then change the below line to your swarm install url:
SWARM_HOST="Your swarm FQDN or Hostname"
Save and close the script file.
24. Update the P4 Triggers table. With super access we need to change the triggers:
NOTE: If you are using Strict or Enforce triggers, you must add the Swarm Admin user, and the local file system path to the .p4tickets file that contains a valid ticket for the Swarm Admin user to the trigger script.
$ p4 triggers
Add these form, shelve, and change triggers:
swarm.job form-commit job "/opt/perforce/server/swarm-trigger.sh -t job -v %formname%"
swarm.user form-commit user "/opt/perforce/server/swarm-trigger.sh -t user -v %formname%"
swarm.userdel form-delete user "/opt/perforce/server/swarm-trigger.sh -t userdel -v %formname%"
swarm.group form-commit group "/opt/perforce/server/swarm-trigger.sh -t group -v %formname%"
swarm.groupdel form-delete group "/opt/perforce/server/swarm-trigger.sh -t groupdel -v %formname%"
swarm.change form-commit change "/opt/perforce/server/swarm-trigger.sh -t change -v %formname%"
swarm.shelve shelve-commit //... "/opt/perforce/server/swarm-trigger.sh -t shelve -v %change%"
swarm.commit change-commit //... "/opt/perforce/server/swarm-trigger.sh -t commit -v %change%"
Setup for a Windows based Perforce Server is available here.
25. Swarm is now set up and ready to use.
If you encounter issues with your Swarm setup, please double-check the steps above. If you are unable to resolve the problem, please consult the Swarm documentation in any of these locations:
- Click on "Help" within Swarm itself
- Swarm documentation on the Perforce website
- In the Swarm install directory, there is a folder called 'Readme', which contains some helpful documents
- Swarm log, found under the data directory will also output any specific errors.