Skip to content

Latest commit

 

History

History
254 lines (191 loc) · 12.1 KB

install-helix-swarm.md

File metadata and controls

254 lines (191 loc) · 12.1 KB
Raw

Helix Swarm installation guide

In this guide, we explain how to install and configure Helix Swarm to review your colleagues changes.

Helix Swarm review page

Installation

⚠️ In Helix Swarm official documentation, they require to "not prefix group names, project names, user names, or client-names with "swarm-", this is a reserved term used by Swarm. Prefixing a name with "swarm-" will result in unexpected and unwanted behavior in Swarm".

  1. From the official documentation, Swarm requires an automated user with at least admin privileges in the Helix Core Server to enable Swarm to run against the Helix Core Server. For this, create a perforce group, sets the Duration before login sessions times out to unlimited and add your swarm user. Now you Helix Swarm could use a long-lived login ticket.

  2. Copy the docker-compose.yaml file in your server and change the Helix Swarm settings containing YOUR_ with your configuration :

    version: '3'

services:
    helix-swarm:
        image: perforce/helix-swarm
        hostname: helix-swarm
        container_name: helix-swarm
        domainname: helix-swarm
        restart: unless-stopped
        volumes:
            - ./data:/opt/perforce/swarm/data
            - ./certificates:/etc/apache2/ssl
        environment:
            - P4D_PORT=<YOUR_P4PORT> # e.g. ssl:192.168.1.10:1666
            
            # Superuser and swarm user must not use the Helix Authentication Service :
            # https://www.perforce.com/manuals/swarm-admin/Content/Swarm/setup.dependencies.html#Helix_Core_Server_automated_user_requirements_for_Swarm
            - P4D_SUPER=<YOUR_SUPER_USER>
            - P4D_SUPER_PASSWD=<YOUR_SUPER_USER_PWD>
            - SWARM_USER=<YOUR_SWARM_SUPER_USER>
            - SWARM_PASSWD=<YOUR_SWARM_SUPER_USER_PWD>

            # Your server ip / host name to be accessible by Helix Core server (e.g 192.168.1.101 or helix-swarm)
            # and by your users.
            - SWARM_HOST=<YOUR_SWARM_HOSTNAME>

            # If set to 'y', then extensions will be installed even if they already
            # exist, overwriting existing configuration.
            - SWARM_FORCE_EXT=y
        ports:
            - 80:80
            - 443:443
        working_dir: /opt/perforce/swarm
        depends_on:
            - helix-redis
        tty: false
        # networks:
        #    - nginx-proxy

    helix-redis:
        image: greenbone/redis-server
        container_name: helix-redis
        restart: unless-stopped
        user: root
        command: redis-server --protected-mode no --port 7379 --appendonly yes
        # networks:
        #    - nginx-proxy

# networks:
#    nginx-proxy:
#       external: true

    ⚠️ If Helix Authentication Service is configured for your Helix Core Server, the user account running Swarm must not use the Helix Authentication Service.

    As Perforce mentioned in their website, Swarm log files, the worker queue, tokens and workspaces will be preserved in their volume.

  3. (Optional) If you want to use an anonymous account, pull greenbone/redis-server and perforce/helix-swarm from portainer or run :

    sudo docker pull perforce/helix-swarm && sudo docker pull greenbone/redis-server

  4. (Optional) If you install Nginx Proxy Manager, add a new proxy host and use the forward port 80. You will also need to change the hostname and domainname of the docker-compose with your new subdomain (e.g swarm.example.com) to be accessible by both your Helix Core Server and your users.

  5. Deploy your container :

    sudo docker-compose up -d

  6. Follow the official documentation to validate your Swarm installation.

Configuration

⚠️ For each step, Swarm will not use it until you reload the cache configuration.

HTTPS

  1. Follow the official documentation and don't forget to back-up /etc/apache2/sites-available/perforce-swarm-site.conf configuration file.

SSO with Helix Authentication Service

  1. In Portainer, open a terminal in Helix Swarm container or run :

    sudo docker exec -it helix-swarm /bin/bash

  2. Since Swarm 2024.1, you only need to set the sso variable to 'enabled' or 'optional' in /opt/perforce/swarm/data/config.php file. Choose the value that matches your needs :

    • 'enabled' : all users must use Helix Authentication Service to log in to Swarm.
    • 'optional' : Helix Authentication Service is available for users to log in to Swarm but is not enforced.

    Here is an example :

        'p4' => array(
    'port' => '<YOUR_P4_PORT>',
    'user' => '<YOUR_SWARM_USER>',
    'password' => '<YOUR_SWARM_PWD_HAS>',
    'sso' => 'optional',
    ),

Recommended review settings

  1. In Portainer, open a terminal in Helix Swarm container or run :

    sudo docker exec -it helix-swarm /bin/bash

  2. Add a new section in the configuration file (/opt/perforce/swarm/data/config.php) :

        // this block should be a peer of 'p4'
    'reviews' => array(
        // Disable approve for reviews with open tasks
        'disable_approve_when_tasks_open' => true,
        // Disable self-approval of reviews by authors
        'disable_self_approve' => true,
        // Protected end states by blocking edit after a review has been approved
        'end_states' => array('archived','rejected', 'approved:commit'),
        // Process shelf file delete when a review has not been approved
        'process_shelf_delete_when' => array('needsReview', 'needsRevision'),
        // Synchronize review description
        'sync_descriptions' => true,

        // When the review has been completed, the user changelist's will be deleted :
        // https://www.perforce.com/manuals/swarm-admin/Content/Swarm/admin.review_cleanup.html#Review_cleanup
        'cleanup' => array(
            'mode' => 'auto',
            'default' => true,
            'reopenFiles' => false,   // re-open any opened files into the default changelist
        ),
    ),

    :info: You can find other configurable in Helix Swarm Guide.

Apache Security

  1. In Portainer, open a terminal in Helix Swarm container or run :

    sudo docker exec -it helix-swarm /bin/bash

  2. Edit your apache2 configuration file.

    nano /etc/apache2/apache2.conf

  3. Add these lines to the end of the file :

    # Apply Helix security settings :
# https://www.perforce.com/manuals/swarm-admin/Content/Swarm/admin.security.html#Apache_security

# Disable Apache identification (version, installed modules...)
ServerSignature Off
ServerTokens ProductOnly

# Disable trace requests that may disclose cookie information
TraceEnable off

  4. Now, edit the ssl modules.

    nano /etc/apache2/mods-available/ssl.conf

  5. Add or modify the following parameters :

            SSLHonorCipherOrder On
        SSLCipherSuite ECDHE-RSA-AES128-SHA256:AES128-GCM-SHA256:RC4:HIGH:!MD5:!aNULL:!EDH
        SSLCompression Off

  6. Restart your apache2 server.

    apachectl restart

Email Delivery using Gmail server

  1. In Portainer, open a terminal in Helix Swarm container or run :

    sudo docker exec -it helix-swarm /bin/bash

  2. Add a new section in the configuration file (/opt/perforce/swarm/data/config.php) and replace with your settings :

    // this block should be a peer of 'p4'
// Official documentation : https://www.perforce.com/manuals/swarm-admin/Content/Swarm/admin.email.html
'mail' => array(
    'transport' => array(
        'name' => 'smtp.gmail.com',                 // name of SMTP host
        'host' => 'smtp.gmail.com',                 // host/IP of SMTP host
        'port' => 587,                              // SMTP host listening port
        'connection_class'  => 'plain',             // 'smtp', 'plain', 'login', 'crammd5'
        'connection_config' => array(
            'username'  => '<YOUR_GMAIL_ADDRESS>',  // user on SMTP host
            'password'  => '<YOUR_APP_PASSWORD>',   // password for user on SMTP host
            'ssl'       => 'tls'
        ),
    ),
    // Setting the value to true, conceals the email addresses of all recipients.
    'use_bcc' => true,
),

    :info: You will find other configuration in the official documentation.

  3. Now, change the state of a review and it will automatically send an email.

References