Moving your Swarm instance

This section describes how to move your Swarm instance to another server. This can be useful if you want to move Swarm to a different server to improve performance or if you want to run Swarm on a newer operating system. Swarm data is held on the Helix Core server and not in Swarm so there is no need to migrate any data to your new Swarm instance.

Note

If you are installing a newer version of Swarm than your original Swarm instance, you might need to configure options if they are not already present in you original version of Swarm.

For example, Swarm workflow, updated trigger scripts, the introduction of a Redis cache, and changes to custom modules. For information on important changes to Swarm, see the Important information section of the Swarm What’s new page.

Summary

The process for moving your Swarm installation to another server is summarized below:

  1. Install Swarm on a new server.

  2. Copy your original Swarm config.php file and authentication token to your new Swarm instance.

  3. Copy the Swarm trigger script to your Helix server machine and install the swarm-trigger.conf file on your new Swarm instance.

  4. Shutdown your original Swarm instance and start your new Swarm instance .

    5. Warning

    Downtime occurs at this step.

  5. Validate that your new Swarm instance is working correctly.

For step by step instructions for moving your Swarm instance, see Moving Swarm.

Moving Swarm

Moving your Swarm installation to a new server results in downtime, but this process minimizes it.

Installing Swarm on your new server

Choose one of the following installation methods (we recommend the package installation method whenever possible):

Copying your existing Swarm configuration

  1. Copy your original SWARM_ROOT/data/config.php file to your new Swarm instance.

  2. Create the queue token directory on your new Swarm instance:

    mkdir SWARM_ROOT/data/queue

  3. Copy your original trigger token(s) from the SWARM_ROOT/data/queue/tokens to your new Swarm instance.

  4. Assign correct ownership to the new Swarm instance data directory:

    sudo chown -R www-data SWARM_ROOT/data
    Note

    The www-data user above is an example of what the web server user name might be, and can vary based on distribution or customization. For example, the user is typically apache for Red Hat/Fedora/CentOS, www-data for Debian/Ubuntu, wwwrun for SuSE, _www for Mac OSX.

  5. Continue with the next task, see Updating your triggers.

Updating your triggers

Before you begin

The Swarm Workflow feature was introduced in Swarm 2018.2 and was disabled by default, this feature is now enabled by default for Swarm 2019.2 and later.

If you are not currently using the Swarm workflow feature and you are using the strict and enforce triggers to control commits you have the following options:

  • Use the Swarm workflow feature: you must comment out your strict and enforce triggers and use the new workflow triggers.

    • Note

    Known limitations

    The workflow triggers do not support the following trigger functionality available in Swarm 2018.1 and earlier:

    • EXEMPT_FILE_COUNT
    • EXEMPT_EXTENSIONS

    To continue to use this trigger functionality, you must keep your existing enforce and strict triggers and disable the Workflow feature as shown below.

  • Continue to use the strict and enforce triggers: keep your existing enforce and strict triggers and Disable the Workflow feature. Support for these triggers will be dropped in a later release.

    Tip

    If you disable the workflow feature in the Swarm config.php file, workflow will not be processed by Swarm but a small overhead is still incurred by the Helix server each time it runs a workflow trigger script. This overhead can be eliminated by commenting out the swarm.enforce change-submit, swarm.strict change-content, and swarm.shelvesub shelve-submit workflow triggers.

Decide whether you want to use the workflow feature before you start your upgrade because this will determine which triggers you need to use. The trigger requirements are described in more detail in the Update your triggers stage of the Swarm upgrade.

Update your triggers

  1. Copy the new Swarm trigger script to your Helix Core server machine. The trigger script is SWARM_ROOT/p4-bin/scripts/swarm-trigger.pl, and requires installation of Perl 5.08+ (use the latest available) on the Helix server machine. If Swarm is using SSL, then the triggers also require the IO::Socket::SSL Perl module.

    Warning

    Do not overwrite any existing trigger script at this time. Give the script a new name, for example: swarm-trigger-new.pl.

  2. Configure the Swarm trigger script by creating, in the same directory on the Helix server machine, swarm-trigger.conf. It should contain:

    Note

    If you already have a swarm-trigger.conf file, no additional configuration is required.

    # SWARM_HOST (required)
# Hostname of your Swarm instance, with leading "http://" or "https://".
SWARM_HOST="http://my-swarm-host"

# SWARM_TOKEN (required)
# The token used when talking to Swarm to offer some security. To obtain the
# value, log in to Swarm as a super user and select 'About Swarm' to see the
# token value.
SWARM_TOKEN="MY-UUID-STYLE-TOKEN"

# ADMIN_USER (optional) Do not use if the Workflow feature is enabled (default)
# For enforcing reviewed changes, optionally specify the normal Perforce user
# with admin privileges (to read keys); if not set, will use whatever Perforce
# user is set in environment.
ADMIN_USER=

# ADMIN_TICKET_FILE (optional) Do not use if the Workflow feature is enabled (default)
# For enforcing reviewed changes, optionally specify the location of the
# p4tickets file if different from the default ($HOME/.p4tickets).
# Ensure this user is a member of a group with an 'unlimited' or very long
# timeout; then, manually login as this user from the Perforce server machine to
# set the ticket.
ADMIN_TICKET_FILE=				
										
# VERIFY_SSL (optional)
# If HTTPS is being used on the Swarm web server, then this controls whether
# the SSL certificate is validated or not. By default this is set to 1, which
# means any SSL certificates must be valid. If the web server is using a self
# signed certificate, then this must be set to 0.
# set the ticket.
VERIFY_SSL=1

    Fill in the required SWARM_HOST and SWARM_TOKEN variables with the configuration from any previous Swarm trigger script, typically swarm-trigger.pl.

    Tip

    The ADMIN_USER and ADMIN_TICKET variables were used by the 'enforce triggers' in Swarm 2019.1 and earlier. They can be removed unless you are explicitly disabling workflow and using the deprecated 'enforce triggers'.

    Note

    Swarm 2015.4 and earlier: Swarm trigger script files were available as shell scripts in these earlier Swarm versions, typically swarm-trigger.sh.

    Swarm must now use a Perl trigger script file, typically swarm-trigger.pl.

  3. On Linux: ensure that the script is executable:

    $ sudo chmod +x swarm-trigger-new.pl

  4. Rename the new trigger script:

    On Linux:

    $ mv swarm-trigger-new.pl swarm-trigger.pl

    On Windows:

    C:\> ren swarm-trigger-new.pl swarm-trigger.pl

  5. Update the triggers in your Helix server.

    Warning

    • The swarm.shelvedel shelve-delete trigger line was added to Swarm in version 2018.1 and updated in version 2020.1.

      • Upgrading from Swarm 2017.4 and earlier: add the swarm.shelvedel shelve-delete trigger line to the Helix server trigger table if it is not already present, see Update the Helix server triggers table to run the trigger script.
      • Upgrading from Swarm 2018.x and 2019.x: replace the existing swarm.shelvedel shelve-delete trigger line in the Helix server trigger table with the one supplied in the Swarm version you are upgrading to.

    • Workflow feature:

      The Workflow feature is enabled by default in Swarm 2019.2 and later. The trigger lines required when workflow is enabled are different to those required when workflow is disabled:

    1. Run the Swarm trigger script to capture (using Ctrl+C on Windows and Linux, Command+C on Mac OSX) the trigger lines that should be included in the Perforce trigger table:

      On Linux:

      $ ./swarm-trigger.pl -o

      On Windows:

      C:\> path/to/perl swarm-trigger.pl -o

    2. As a Perforce user with super privileges, update the Perforce trigger table by running p4 triggers command and replacing any swarm.* lines with the previously captured trigger line output (using Ctrl+V on Windows and Linux, Command+V on Mac OSX).
    Important

    If you previously customized the Swarm trigger lines, perhaps to apply various Trigger options, be sure to repeat those customizations within the updated trigger lines.

  1. Continue with the next task, see Replacing your original Swarm instance with your new instance.

Replacing your original Swarm instance with your new instance

Warning

Downtime occurs in this step.

Replace your original Swarm instance with your new Swarm instance.

  1. Stop your original Swarm instance:

    2. sudo apache2ctl stop

  2. Start your new Swarm instance:

    3. sudo apache2ctl start

    Note

    If you see the following error message when you start Swarm, Swarm is using the wrong version of P4PHP. The latest version of P4PHP is included with Swarm.

    If you are installing Swarm from a tarball, you must configure Swarm to use that version of P4PHP. For instructions about how to configure Swarm to use the new version of P4PHP, see PHP configuration.

    Image of the P4PHP version error message

  3. Continue with the next task, see Validating your new Swarm instance.

Validating your new Swarm instance

Tip

When Swarm starts it verifies the Redis cache, during this time you cannot log in to Swarm. The time taken to verify the Redis cache depends on the number of users, groups, and projects Swarm has. Start-up time can be improved by persisting the memory cache. You can persist the memory cache by disabling background saves and enabling append saves in the redis-server.conf file, see Redis server configuration file.

Check that your upgraded Swarm instance is working correctly by doing the following:

  1. Create a new changelist that:
    1. Contains at least one modified file
    2. Contains the #review keyword in the changelist description
  2. Right click on the new changelist in P4V and click Shelve Files...

    3. Important

    Do not select Request New Swarm Review... because this method uses the API and will not fully test the Swarm triggers.

  3. Check that a new Swarm review is created for the changelist.
    • If a Swarm review is created, the Swarm triggers are working.
    • If a Swarm review is not created, see below.
Note
  • If a new Swarm review is not created when you validate your upgrade, you may be missing some Swarm triggers on the Helix server. Periodically new triggers are added to Swarm and these need to be installed when you upgrade, see the Update your triggers section above. For more information about Swarm trigger configuration on your Helix server, see Helix Core server configuration for Swarm.

  1. Do one of the following:

    • If your new Swarm instance is working correctly: Retire your original Swarm instance.

    • If your new Swarm instance is not working correctly: Shutdown the new Swarm instance, remove any updates you made to the triggers on the Helix server, and switch back to your original Swarm instance. Check the configuration and connectivity of your new Swarm instance. If you can't find the issue, you can submit a Support Request.