Installing the Swarm Helix Core Server extension (recommended)

Important

If you are using the Swarm Helix Core Server extension, Swarm Helix Core Server Triggers must not be installed.
You must be a user with super user permissions to install and configure Helix Core Server Extensions.

Swarm needs to know about a number of Helix Core Server events to operate correctly, this is done by using Helix Core Server Extensions. Helix Core Server Extensions must be installed and configured on your Helix Core Server to complete your Swarm installation. The Swarm Helix Core Server extension is included with the Swarm product download.

Prerequisites

To install the Swarm Helix Core Server extension you need:

A compatible version of Helix Core Server for Helix Core Server Extensions:

Linux: Helix Core Server 2021.2 and later. If you are using an earlier version of Helix Core Server, you must use triggers.
Windows: Helix Core Server 2021.2 and later. If you are using an earlier version of Helix Core Server, you must use triggers.

You will also need:

Helix Core Server Extensions installed and configured on your Helix Core Server.
A user with super permissions to install and configure the Swarm Helix Core Server extension.

Swarm Helix Core Server extension installation

Tip

The following commands can be run on the Swarm server or the Helix Core Server. You must be a Helix Core Server super user to install and configure Helix Core Server Extensions.

The Swarm Helix Core Server extension file is included for all of the Swarm installation types. The helix-swarm.p4-extension file is located in swarm_root/p4-bin/extensions

Run the following commands as a Helix Core Server user with super permissions:

Install the Swarm Helix Core Server extension on the Helix Core Server with:

p4 extension --yes --install helix-swarm.p4-extension

Example response:

Extension 'Perforce::helix-swarm' version '2022.1.20221215' installed successfully.
Perform the following steps to turn on the Extension:

# Create a global configuration if one doesn't already exist.
p4 extension --configure Perforce::helix-swarm

# Create an instance configuration to enable the Extension.
p4 extension --configure Perforce::helix-swarm --name Perforce::helix-swarm-instanceName

For more information, visit: https://www.perforce.com/manuals/extensions/Content/Extensions/Home-extensions.html

Create a global configuration if one doesn't already exist:

p4 extension --configure Perforce::helix-swarm

The spec file opens in your text editor, for example:

ExtName:        helix-swarm
ExtDescription:
        Helix Swarm Extension
 
ExtVersion:     2022.1.DEV.20220120
 
ExtUUID:        4532BC59-7BC8-478F-ADF6-0A563C42563D
 
ExtRev: 1
 
ExtMaxScriptTime:       unset
 
ExtMaxScriptMem:        unset
 
ExtAllowedGroups:
 
ExtEnabled:     true
 
ExtP4USER:      sampleExtensionsUser
 
Name:   helix-swarm
 
Owner:  super
 
Update: 2022/01/21 10:43:46
 
Description:
        The description of your config.
 
ExtConfig:
        Debug:
                2
        Swarm-Secure:
                true
        Swarm-Token:
                ... SWARM-TOKEN
        Swarm-URL:
                http://localhost/

Edit the spec file to match your system:
- ExtP4USER: Set to an existing user with super permissions.
- ExtConfig: Check and edit the values in this block:
  - Debug:
    
    Debug levels 0 to 3 control the amount of debug information sent to the Helix Core Server Extensions log.
    
    Important
    A debug level of 10 and higher sends all debug information to the client. This is useful for debugging, but should not be run in a production environment.
  - SSL-CA-File: (optional) Set the absolute path of the Certificate Authority (CA) Privacy-Enhanced Mail (PEM) file to validate the SwarmHelix Core Server's certificate. Ensure that this file is accessible to the Helix Core Server process owner.
    
    If a suitable certificate is not found in the local SSL certificate store maintained by the operating system or if there are verification issues from using a self-signed certificate then the default CA file is used.
    
    By default, the local certificate stored in the default CA file is used if the absolute path for the Certificate Authority (CA) is not specified.
  - Swarm-Secure:
    - true will only accept secure SSL certificates.
    - false will accept insecure SSL certificates.
  - Swarm-Token: Set to the Swarm trigger token value.
    
    Important
    To set multiple Helix Core Server token settings for Extensions, repeat the following steps for each Helix Core Server. The process to obtain an extension token of your Swarm instance is similar to obtaining a trigger token of your Swarm instance.
    
    To obtain the trigger token of your Swarm instance:
    1. Log in to Swarm as a super user.
    2. Click your userid, found at the right of the main toolbar.
    3. Select About Swarm.
    4. The About Swarm dialog is displayed and Swarm generates an API token if it doesn't already exist.
    5. Copy the trigger token value displayed at the bottom of the dialog and paste the token into the spec file.
  - Swarm-URL: Set to the URL of your Swarm instance.
When you have finished editing the spec file, save it in your text editor.
Create an instance configuration to enable the extension:

p4 extension --configure Perforce::helix-swarm --name swarm

The spec file opens in your text editor, for example:
```
ExtName:        helix-swarm
 
ExtDescription:
        Helix Swarm Extension
 
ExtVersion:     2022.1.DEV.20220120
 
ExtUUID:        4532BC59-7BC8-478F-ADF6-0A563C42563D
 
ExtRev: 1
 
ExtMaxScriptTime:       unset

ExtMaxScriptMem:        unset
 
ExtEnabled:     true
 
ExtDebug:       none
 
Name:   swarm
 
Owner:  super
 
Update: 2022/01/21 10:58:41

Description:
        The description of your config.

ExtConfig: 
        depot-path:
                //...
        enableStrict:
                true
        enableWorkflow:
                true
        httpTimeout:
                30
        ignoreErrors:
                false
```
We recommend that these settings are left at their default values, but the configuration needs to be run to set the default values.
- enableStrict: Enable strict checking of reviews for workflow. Verifies that the file content in a commit matches the file content of its associated approved review. If one or more files in a commit do not match the content of the file in its associated review, the commit is rejected.
- enableWorkflow: Enable workflow.
- httpTimeout: Timeout (in seconds) when communicating with the Swarm server.
- ignoreErrors: If the server returns an error (timeout, not there), then default to allowing a request. It means workflow rules can be skipped, but if the Swarm server is down it will not block submits.
Save the spec file in your text editor.
Confirm your Swarm Helix Core Server extension is installed and configured by running the following command on the Helix Core Server:

p4 extension --run swarm ping

If the Swarm Helix Core Server extension is working, the Helix Core Server responds with OK
If the Swarm Helix Core Server extension is not working, the Helix Core Server responds with an error message. For example, BAD (Cannot reach https://swarm-example.com/)

For more information about Helix Core Server Extensions, see:

Extension overview in the Helix Core Extensions Developer Guide.
p4 extension in the Helix Core Command-Line (P4) Reference.

Depending on your installation type, do one of the following:
- Swarm package installation: Review the post-install configuration options to customize your Swarm installation, see Post-install configuration options.
- Swarm tarball installation: Set up a recurring task to spawn workers, see Set up a recurring task to spawn workers.

Add Swarm as an HTML tab in the Helix Core Visual Client (P4V)

To add Swarm as an HTML tab in the Helix Core Visual Client (P4V), see HTML Tabs section in the P4VJS Developer Guide.