PmWiki: WikiFarms

WikiFarms are a mechanism for running multiple independent wikis from a single PmWiki installation. If a WikiFarm is a collection of independent wikis, then each wiki in the farm is commonly called a WikiField. A person who manages the PmWiki software installation is commonly called a farm administrator, while any administrators of individual fields are called field administrators. Each field can have its own base URL, set of pages and WikiGroups, uploads, page templates, passwords, and other local customizations.

Most importantly, software upgrades to the (single) farm installation automatically upgrade all of the fields in the farm. In addition, customizations can be made and controlled at the farm level, to be applied to and used by all of the fields in the farm.

The remainder of this document describes how to setup WikiFarms and individual fields of the farm, and assumes you are already somewhat familiar with the details of PmWiki installation.

Setting up a WikiFarm (farm administrator)

Setting up a PmWiki installation to act as a WikiFarm is fairly straightforward. The farm administrator simply creates a local/farmconfig.php file with any local customizations that are to be performed for every field in the farm. Usually, this will mean setting $FarmPubDirUrl and $PageTemplateFmt to reasonable settings for the new field. A minimal farmconfig.php file might look like:

    <?php
      $FarmPubDirUrl = 'http://www.example.com/pmwiki/pub';
      $PageTemplateFmt = "$FarmD/pub/skins/pmwiki/pmwiki-farm.tmpl";
    ?>

$FarmPubDirUrl is used to provide fields with the URL location of the farm's pub/ directory, and $PageTemplateFmt is changed to be a shared "farm" version of the default layout. (The only real difference between the normal template and the farm template is that the farm template uses $FarmPubDirUrl instead of $PubDirUrl in the .css files.)

That's all there is to it--your PmWiki installation is now set up for farming!

Setting up a field within the WikiFarm (field administrator)

Once PmWiki has been set up for WikiFarming, a new field is created by doing the following:

1. Create a directory to hold the field. Normally the field directory goes in a web-accessible directory (e.g., under public_html), but it can be placed anywhere that a PmWiki installation would normally go.

2. Create a PHP script (e.g., field.php) in the field directory with the following line

    <?php include('path/to/pmwiki.php'); ?>

where path/to/pmwiki.php is the path to the farm's installation of PmWiki.

3. Change the field's directory permissions to 2777.

4. Open a web browser and execute the field.php script you created in step #2. This will create the needed directories for the field and should bring up a default PmWiki installation (with any default settings the farm administrator may have set).

Local customizations in fields and farms

Each field administrator can create a local/ directory within the field directory for local customization to be applied to the field. This works just like a normal PmWiki installation--the file local/config.php holds settings for the entire field, and files of the form local/Group.php and local/Group.PageName.php are used for per-group and per-page customizations (see PerGroupCustomizations).

Within a field, the PmWiki variable $FarmD is set to the "home directory" for the PmWiki farm installation, thus an administrator can use $FarmD/scripts/ and $FarmD/pub/ to refer to the farm's scripts/ and pub/ directories.

A farm administrator can use the local/farmconfig.php file for customizations to be applied to all fields within the farm. By default, farm customizations are performed before any field-customization files; however, the farm administrator can override some field-customizations by explicitly calling the field's config.php file, as in:

  <?php
    # Settings performed before field-customizations
    $FarmPubDirUrl = 'http://www.example.com/pmwiki/pub';
    $PageTemplateFmt = "$FarmD/pub/skins/pmwiki/pmwiki-farm.tmpl";

    # load the field's global and per-group customizations
    include_once('local/config.php');
    include_once('local/pgcust.php');

    # Override field customizations here
    $EnableUpload = 0;            # disable uploads
  ?>

Notes

• Field directories can also contain local pub/ and uploads/ directories. A per-field uploads/ directory will normally be created in the field directory if uploads are enabled (see UploadsAdmin).

• Pages distributed with PmWiki (e.g., documentation) are automatically shared among all fields in a farm. This is controlled through the $WikiLibDirs variable, which defaults to looking in the farm's copy of wikilib.d/.

• The file farmmap.txt in the farm's local/ directory can be used to provide farm-wide InterMap links. This may be useful for creating links to pages in other fields of the farm.

• In general, fields can be created and administered from user accounts other than the one maintaining the farm if the underlying operating system permissions and PHP configuration settings allow it. PHP's default configuration normally allows this, but some system administrators and web hosting services change the PHP configuration such that this is not possible.

See also Cookbook.WikiFarm? and Cookbook.WhichFarmToUse?.