Environment

This section describes the environment configuration items available for Swarm:

  • mode: whether Swarm operates in production or development mode.
  • hostname: specifies the canonical hostname Swarm should use, such as in links to Swarm in email notifications.
  • external_url: specifies the canonical URL Swarm should use, such as in links to Swarm in email notifications and in test callback URLs. Swarm can often auto-detect the correct URL, but use of external_url might be necessary in complex web hosting environments.
  • base_url: specifies the folder name Swarm is installed within when Swarm is not installed in the web server's document root.
  • logout_url: specifies the URL that users are redirected to when they logout of Swarm.
  • emoji_path: specifies the location the Gemoji images are stored in.
Tip

If you make a configuration change, Swarm will not use it until the configuration cache has been reloaded, this forces Swarm to use the new configuration. You must be an admin or super user to reload the Swarm config cache. Navigate to the User id dropdown menu, select System Information, click the Cache Info tab, and click the Reload Configuration button.

Add the following configuration block to the SWARM_ROOT/data/config.php file:

<?php
    // this block should be a peer of 'p4'
    'environment' => array(
        'mode'         => 'development',      // defaults to 'production'
        'hostname'     => 'myswarm.hostname', // defaults to requested hostname
        'external_url' => null,               // defaults to null
        'base_url'     => null,               // defaults to null
        'logout_url'   => null,               // defaults to null
        'vendor'       => array(
            'emoji_path' => 'vendor/gemoji/images',
        ),
    ),

mode

By default, Swarm operates in production mode. When mode is set to development, Swarm displays greater error detail in the browser. Also, Swarm switches from including aggregated and minified JavaScript and CSS to requesting each JavaScript and CSS resource for all active modules. The default value is production. Any value other than development is assumed to mean production.

development mode makes it easier to discover problems and to identify their source, but also incurs additional browser overhead due to many more JavaScript and CSS requests for larger files. We recommend that you do not use development mode in production environments, unless directed to do so by Perforce technical support.

hostname

The hostname item allows you to specify Swarm's hostname. This could be useful if you have multiple virtual hosts deployed for a single Swarm instance; Swarm uses the hostname you configure when generating its web pages and email notifications.

Note

The value specified for the hostname item should be just the hostname. It should not include a scheme (e.g. "http://"), nor should it include a port (e.g. ":80").

external_url

The external_url item allows you to specify Swarm's canonical URL. This is useful if your Swarm instance is proxied behind another web service, such as a load balancer, caching proxy, etc., because Swarm's auto-detection of the current hostname or port could otherwise result in incorrect self-referencing URLs.

When specified, Swarm uses the external_url item as the prefix for any URLs it creates that link to itself in its web pages, email notifications, and test callback URLs.

Note

  • Any path components included in external_url are ignored. If you specify https://myswarm.url:8080/a/b/c, Swarm only uses https://myswarm.url:8080/ when composing URLs.

  • If you set the external_url for Swarm, disable the auto_register_url feature in Swarm. For information about disabling the auto_register_url feature for Swarm, see Client integration.

Important

Multiple Swarm instances connected to a single Helix Core Server instance:

If you specify base_url along with external_url, ensure that all Swarm instances specify the same base_url. Varying base_url amongst cooperating Swarm instances is not supported.

base_url

The base_url item allows you to specify Swarm's folder within the web server's document root. This is useful if you cannot configure Swarm to operate within its own virtual host, such as when you have an existing web service and Swarm must exist alongside other applications or content. For information on configuring Swarm to run within a sub-folder of an existing website, see Run Swarm in a sub-folder of an existing web site.

Tip

The swarm-trigger.conf file must be updated to include the base_url in the SWARM_HOST path, see Swarm trigger configuration

By default, base_url is null, which is equivalent to specifying /. If you specify a folder, include the leading /. For example, /swarm.

Warning

Multiple Helix Core Server instances on a single Swarm instance:

Issue: Swarm will lose connection to all of the Helix Core Servers if you edit the base_url configurable value in the environment block of <swarm_root>/data/config.php. This will stop your system working.

Fix: Remove the base_url configurable from the environment block of <swarm_root>/data/config.php.

Important

Multiple Swarm instances connected to a single Helix Core Server instance:

If you specify external_url along with base_url, ensure that all Swarm instances specify the same base_url. Varying base_url amongst cooperating Swarm instances is not supported.

logout_url

The logout_url configurable is used to automatically redirect users to a custom URL after they have logged out of Swarm.

When the logout_url item is set and you log out of Swarm:

  • Using Log out from Swarm: you are logged out by Swarm and then redirected to the custom URL.
  • Using Log out from a single Swarm instance on the global dashboard: you are logged out of the Helix Core Server instance by Swarm. You are only redirected to the custom URL if you are not logged in to any other Helix Core Server instances on the global dashboard.
  • Using Log out from all instances on the global dashboard: you are logged out of all of the Helix Core Server instances by Swarm and then redirected to the custom URL.

To redirect users to a custom URL after they have logged out of Swarm, edit the SWARM_ROOT/data/config.php file and set the logout_url configurable to the URL you want to redirect users to:

<?php
    // this block should be a peer of 'p4'
    'environment' => array(
        'logout_url'   => <http[s]://your/redirect/logout/url>, // defaults to null
    ),

The default value is null, users are not redirected when they log out of Swarm.

emoji_path

The emoji_path configurable defines the location of the Gemoji images in SWARM_ROOT/public/.

To change the location of the Gemoji images, edit the SWARM_ROOT/data/config.php file and set the emoji_path configurable to the location the Gemoji images are stored in:

<?php
    // this block should be a peer of 'p4'
    'environment' => array(
        'vendor'   => array(
            'emoji_path' => 'vendor/gemoji/images',
        ),
    ),

The default location is vendor/gemoji/images, this means that by default images are stored in SWARM_ROOT/public/vendor/gemoji/images.

Further information

For instructions on downloading Gemoji and configuring Swarm to use the images, see Emoji.