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.

Summary

Moving your Swarm installation to a new server results in downtime, but the following process minimizes it. 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. Only required if you are moving to a newer version of Swarm: Configure your new Swarm instance to receive event notifications from the Helix Core Server.

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

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, start by Installing Swarm on your new server.

Installing Swarm on your new server

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

• Install and configure Swarm from a package (recommended). Do not follow the Post-installation configuration steps. Copy your original Swarm config.php file to your new Swarm instance, see Copying your existing Swarm configuration.

• Install and configure Swarm manually from a Tarball, configure Redis, configure Apache, and configure PHP. Copy your original Swarm config.php file to your new Swarm instance, see Copying your existing Swarm configuration.

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/CentOS and www-data for Debian/Ubuntu.

5. Do one of the following:

   • If moving to an instance with the same Swarm version: go to Replacing your original Swarm instance with your new instance.

   • If moving to an instance with a newer version of Swarm: go to Configuring Helix Core Server event notification.

Configuring Helix Core Server event notification

Swarm needs to know about a number of Helix Core Server events to operate correctly, this can be done by using Helix Core Server Extensions or Helix Core Server Triggers.

You must configure your new Swarm instance to receive event notifications from the Helix Core Server to complete the Swarm move.

Do one of the following so that Swarm is notified about events on the Helix Core Server:

• If your old Swarm instance is using Helix Core Server Extensions: update the Swarm Helix Core Server extension configuration, see Updating your Swarm Helix Core Server extension

• If your old Swarm instance is using Helix Core Server Triggers: update your Swarm Triggers, see Updating your triggers

Updating your Swarm Helix Core Server extension

If you are moving a Swarm instance that is already using Helix Core Server Extensions, there is no need to reinstall the extension because it is already installed on Helix Core Server.

To update your Swarm Helix Core Server extension:

1. Open the extension configuration file with:

p4 extension --configure Perforce::helix-swarm

The spec file opens in your text editor

2. Edit the configuration for your new Swarm instance as required.

3. Swarm-URL: do one of the following:

   • If the hostname of your Swarm server has changed: set the Swarm-URL to the URL of your new Swarm server instance.

   • If the Swarm server hostname has not changed: you do not need to change the Swarm-URL in the configuration file.

4. Save the configuration changes.

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

Updating 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 Core 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 Core 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:

   ren swarm-trigger-new.pl swarm-trigger.pl

5. Update the triggers in your Helix Core 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 Core Server trigger table if it is not already present, see Update the Helix Core 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 Core 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:

     • Workflow feature enabled (default):
       • Comment out the swarm.enforce.1, swarm.enforce.2, swarm.strict.1, and swarm.strict.2 trigger lines in the Helix Core Server trigger table if they are present, see Update the Helix Core Server triggers table to run the trigger script.
       • Add the swarm.enforce change-submit, swarm.strict change-content, and swarm.shelvesub shelve-submit trigger lines to the Helix Core Server trigger table if they are not already present, see Update the Helix Core Server triggers table to run the trigger script.
     • Workflow feature disabled:

       Comment out the swarm.enforce change-submit, swarm.strict change-content, and swarm.shelvesub shelve-submit trigger lines in the Helix Core Server trigger table if they are present, see Update the Helix Core Server triggers table to run the trigger script.

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

      On Linux:

      ./swarm-trigger.pl -o

      On Windows:

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

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

Replacing your original Swarm instance with your new instance

Replace your original Swarm instance with your new Swarm instance.

1. Stop your original Swarm instance:

sudo apache2ctl stop

2. Start your new Swarm instance:

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.



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

Validating your new Swarm instance

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

Do not select Request New Swarm Review... because this method uses the API and will not fully test the Swarm Helix Core Server extension.

This is also true if you are using Swarm Helix Core Server Triggers instead of the Swarm Helix Core Server extension.

3. Check that a new Swarm review is created for the changelist.
• If a Swarm review is created, the Swarm Helix Core Server extension is working. If you are using Swarm Helix Core Server Triggers instead of the Swarm Helix Core Server extension and the review is created, the triggers are working.
• If a Swarm review is not created, see Review not created.

4. 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 or extensions on the Helix Core 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.