Deploy and configure a Swarm VM from an OVA

Swarm is available as an OVA (Open Virtualization Appliance) that requires minimal configuration.

Use the Swarm OVA if you want to:

• Simplify the installation and configuration steps
• Experiment with Swarm without using additional hardware
• Install Swarm without having a Linux-based server available

Before you begin

You will need the following information to deploy the Swarm Virtual Machine (VM) from the OVA:

• The Helix Core Server port (P4PORT) in the form: my-helix-core-server:1666
Important

If your Helix Core Server is deployed using the commit-edge architecture, ensure that the Swarm port value points to the commit server.

For more information, see the Commit-edge chapter in the Helix Core Server Administrator Guide.

• The Userid of a normal user in the Helix Server with admin privileges.
• The Ticket, or password of the admin-level Perforce user.
Important

You must use a long-lived login ticket for the Swarm user.

• The Mail relay host address.
• A user with super permissions to install and configure Helix Server Extensions.

Deploy the Swarm OVA

To deploy the Swarm OVA:

1. Download the Swarm OVA.
2. Import the OVA into your virtualization environment, see VMWare OVA import or Oracle VirtualBox import for details.
3. Set the VM network settings to Bridged so that it can connect to your network.
4. Start the VM.
Note

If you are starting your VM in VMware Workstation, you might see an import failed error dialog. If you see this error dialog, click Retry to start your Swarm VM.

Diagnostic and boot information is displayed when the VM starts.

The configuration welcome screen is displayed when the boot is complete:



5. Follow the configuration script prompts to configure the perforce system user password and the hostname for the VM:

   1. Set a password for the perforce system user. The perforce system user is a sudo user.
   2. Set a hostname for the VM.
   Tip

   The SSH IP address of the VM is displayed when you set the hostname, make a note of it because you need this address to ssh into the VM.

6. The configuration script displays the following prompt:

   Do you want to proceed with Swarm configuration (Y/n)?

   Choose one the following two options:

   • Proceed with VM configuration, see Proceed with the Swarm VM configuration script for details.

   or

   • Exit the Swarm VM configuration script to make changes from the VM operating system and then return to the Swarm configuration script. For example, you may need to edit the VM network configuration or install P4D on the same VM. See Exit the Swarm VM configuration script for details.

   Proceed with the Swarm VM configuration script

   1. To proceed with the Swarm VM configuration script, press the Enter key.
   2. Press the Enter key again to restart the Swarm VM configuration script.
   3. Finalize Swarm VM configuration, see Finalize Swarm configuration for details.

   Exit the Swarm VM configuration script

   1. To exit the Swarm VM configuration script, type n and press the Enter key
   2. The Swarm configuration script exits and you can log in to the VM.
   3. Log in to the VM as the perforce system user:
      • Username: perforce
      • Password: the password you set in step 4
   4. Make changes to the VM as required.

   5. When you have finished making changes to the VM, rerun the configure-swarm.sh script from the /opt/perforce/swarm/sbin directory:

      sudo /opt/perforce/swarm/sbin/configure-swarm.sh

   6. Finalize Swarm VM configuration, see Finalize Swarm configuration for details.

Finalize Swarm configuration

Follow the Swarm configuration script prompts to finalize Swarm VM configuration:

1. Enter the Helix Core Server port (P4PORT) number.

   Important

   If your Helix Core Server is deployed using the commit-edge architecture, ensure that the Swarm port value points to the commit server.

   For more information, see the Commit-edge chapter in the Helix Core Server Administrator Guide.

2. Enter the Userid of a normal user with admin privileges in the Helix Server.
3. Enter the Ticket, or password, of the admin-level Perforce user.
Important

You must use a long-lived login ticket for the Swarm user.

Note

You can obtain a login ticket by running (in another shell):

p4 -p myp4host:1666 -u userid login -p

If the login ticket you provide expires in less than a year, you will receive a warning. If you receive this warning, ask your Helix Server administrator to make sure the swarm user is in a Helix Server group that has the Timeout field set to a year or more. See p4 group in the Helix Core Command-Line (P4) Reference.

4. Enter the Mail relay host address.

5. To enable file attachments on comments, Swarm must have a depot location to save the attachment files in. Swarm can create this depot and set the depot protections for you automatically or you can manually set it up later.

   Important

   You must be a user with super user permissions to create the .swarm depot and set protections.

   - checking depot 
   
   Swarm has the ability to store attachments against review comments. To
   do this, it needs to have a depot where they are stored. By default,
   this is //.swarm. We can create the depot for you automatically, and
   set the protections on it to the following: 
   
   list user * * -//.swarm/...
   admin user swarm * //.swarm/...
   super user super * //.swarm/...
    
   If you want to enable attachments, and for the depot and protections
   to be set up for you, then say yes here. If you say no, then you can
   still do this manually later.
   Do you want to create a .swarm depot and set protections? (y/n) [n]

   When prompted to automatically create the depot, select one of the following:

   • Type y to automatically create the .swarm depot and set protections.

   • Type n skip depot creation. You can create the depot and set the protections manually later if you want to, see Comment attachments.

   If you choose to automatically create the depot, the script will create the depot, set the protections, and report when completed.

   Depot //.swarm successfully created. Protections have been set so
   that only the 'swarm' and 'super' have permissions to
   access it directly. 

6. Swarm needs to know about some Helix Server events to operate correctly. Use Helix Server Extensions (recommended) or Helix Server Triggers to notify Swarm about these events. Helix Server Extensions are easier to install and maintain than triggers.

   Important

   You must be a user with super user permissions to install and configure Helix Server Extensions.

   Do you want to use Swarm's Helix Core server extension?
   Configuring Server extensions requires super user access to the Helix Server.
   If you install the Swarm server extension, do not install the Swarm triggers.
   Server extensions are supported for:
   * Linux: Helix server 19.2 and later.
   * Windows: Helix server 21.2 and later. 
   
   Use server extensions? 

   When prompted to Use server Extensions, choose one of the following:

   • Recommended: Type y to use Helix Server Extensions. The configuration script will try and install and configure the Swarm Helix Server extension.

   • Type n to use Helix Server Triggers. Triggers must be installed manually, Swarm will prompt you to do this when the Swarm configuration script completes.

   Note

   If you choose to install the Swarm Helix Server Extensions, the script will:

   • check your Helix Server supports Helix Server Extensions

   • check if Helix Server Extensions are installed and configured on your Helix Server. If they are, Swarm does not need to do anything

   • install and configure the Swarm Helix Server extension on your Helix Server

   If any of these checks fail, Swarm will not install the Swarm Helix Server extension and will report the issues on the configuration summary screen.

The Swarm configuration script completes the configuration and the welcome screen is displayed.

The welcome screen has links to the Swarm documentation, Perforce support, and the PHP website:



7. Update the VM with security updates and bug fixes:

   1. Use ssh to log into the VM as the perforce system user.

   2. Update the catalog of available packages:

      apt-get update

   3. Download and install any updated packages:

      apt-get upgrade

   See OVA Management for more details.

Note

Now that the Swarm VM is configured and running, you can edit the configuration by using ssh to connect to the VM as the system swarm user and editing the Swarm configuration file /opt/perforce/swarm/data/config.php. The Swarm installation folder is /opt/perforce/swarm/.

8. The basic Swarm configuration is now complete.

   Important

   If your Helix Server is configured for Helix Authentication Service, you can force all of your users to authenticate via your Identity Provider (IdP) by disabling fall-back to passwords. To disable fall-back to passwords on the Helix Server, run the following command:

   p4 configure set auth.sso.allow.passwd=0

9. Do one of the following:

   • If the Swarm Helix Server extension was installed by the configuration script: Review the post-install configuration options to customize your Swarm installation, see Post-install configuration options.

   • If the Swarm Helix Server extension was not installed, you must install triggers: Configure Helix Core Server for Swarm, see Installing Triggers.

VMWare OVA import

The Swarm OVA works with several VMWare virtualization products, such as Player, Workstation, and Fusion.

1. In the VMWare product, select File > Open.
2. Browse to the swarm.ova file and click Open.
3. Type a name for the virtual machine, such as Swarm, and click Import.

Oracle VirtualBox import

The Swarm OVA works with Oracle VirtualBox, version 4.x+.

1. In VirtualBox, select File > Import Appliance.
2. Browse to the swarm.ova file and click Open.
3. Click Next.
4. Click Import.