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. Often, 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.

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

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 and email notifications.

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.

Important

If you specify base_url along with external_url and you have deployed multiple Swarm instances that connect to the same Helix Versioning Engine, 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.

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

Important

If you specify external_url along with base_url and you have deployed multiple Swarm instances that connect to the same Helix Versioning Engine, ensure that all Swarm instances specify the same base_url. Varying base_url amongst cooperating Swarm instances is not supported.