administrators (intermediate)
Also see: Cookbook:Farm Setup By Example, Cookbook:Wiki Farm Alternative
A WikiFarm is a collection of two or more wikis running on the same web server and sharing a set of common components. The term is based on the computing phrase "server farm".
This page provides some background information about WikiFarms and describes how to turn a "normal" configuration into a farm by adding a wiki. (Click here to go directly to instructions on configuring a farm.) There are many ways to configure wiki farms; this page describes only one, in an effort to make it as simple as possible for the administrator who is creating a farm for the first time.
This page will discuss 3 ways to organize content:
When you divide content between independently installed wikis (i.e., with their own separate URL), it is difficult (but not impossible) to provide services that require access to more than one wiki. For example, the PmWiki search function can only search within one wiki. Using a farm as a way of subdividing related content is generally a bad idea. A much better way to subdivide content is to use WikiGroups.
When content is largely unrelated and there will be little or no need for sharing the data between the sites, it makes sense to divide the wikis into independently installed sites.
Once you have decided that you need a separate wiki (with its own URL), you have two basic choices:
The primary motivation for using a wiki farm is to reduce the amount of administrative work involved in managing several wikis. In a farm, most of the PmWiki code is stored in one place and is shared by all the wikis. An administrator can (for example) upgrade to a new version of PmWiki on every wiki in the farm by simply updating the shared components in a single location.
From a reader's point of view, there is no difference between separate, self-contained installations of PmWiki and separate wikis within a WikiFarm: each wiki in a farm is completely independent, and appears as a separate web site. Each wiki in a farm:
The good news is that you don't have to decide in advance. In fact, the recommended procedure is to first do a "normal" or single installation of PmWiki. Use it for a while. Create pages and edit them. Get to know how to add recipes. Be sure to try out WikiGroups (they may be all you need).
If you choose to create a wiki farm, then read on ...
Before you create a farm, make sure that:
You do have a working installation of PmWiki at this point, don't you? That's good, because your existing wiki is about to become the home wiki of your farm.
In the directory that contains your existing wiki, create the file local/farmconfig.php. This file is used to hold any local customizations that apply across the whole farm. For example, you could assign an admin password in farmconfig.php that will be used by all of the wikis in your farm.
If the URL used to access your existing wiki is https://www.example.com/pmwiki/ then a minimal farmconfig.php file would look like this:
<?php if (!defined('PmWiki')) exit();
$FarmPubDirUrl = 'https://www.example.com/pmwiki/pub';
This loads the variable $FarmPubDirUrl with the URL location of your home wiki's pub/ directory. All of the wikis in your farm share this pub/ directory. The pub/ directory holds skin definitions and GUI-edit buttons to be shared by all the wikis in the farm.
Amazing as it may sound, this completes all of the changes you need to make in order to turn your existing wiki into the home wiki of your farm.
<?php include_once('path/to/pmwiki.php');
path/to/pmwiki.php is the file path to pmwiki.php in your home wiki. Use an absolute file path (/home/username/pmwiki/pmwiki.php) or a relative file path (../pmwiki/pmwiki.php). Do not use a url path - there should not be an 'https://' in it anywhere. For a web server running under Windows, you need to use a complete file path as in C:/Apache Group/Apache2 /www/mynewwiki/.
https://'. PmWiki will attempt to automatically create a writable wiki.d/ directory where the wiki's pages will be stored. If you see an error message, follow the instructions. If you choose the option for a "slightly more secure installation" be sure to execute both commands.
Your new wiki is now set up, and your farm now contains 2 wikis. To add more wikis, just repeat these 3 steps.
Each wiki in a farm inherits the settings stored in farmconfig.php. Do any customization that you want to apply farm-wide (to all the wikis) in farmconfig.php.
Create a local/ directory within each wiki's directory to hold local customizations that apply only to that wiki. You should at least create the local/config.php file with a new title, like so :
<?php if (!defined('PmWiki')) exit();
## Title of your farmed wiki
$WikiTitle = 'New Wiki';
Farm-wide customizations are processed before the individual wiki local customizations.
The PmWiki variable $FarmD points to the directory in which pmwiki.php is installed, and your home wiki, and it is used as a prefix to allow the other wikis to share PmWiki components. For example:
$FarmD/scripts/ points to the shared scripts/ directory
$FarmD/pub/ points to the shared pub/ directory
$FarmD/cookbook/ points to the shared cookbook/ directory
Any Cookbook scripts you include in farmconfig.php must be included with a line such as:
How come when I switch to another wiki within a farm, I keep my same authorization?
PmWiki uses PHP sessions to keep track of authentication/authorization information, and by default PHP sets things up such that all interactions with the same server are considered part of the same session.
An easy way to fix this is to make sure each wiki is using a different cookie name for its session identifier. Near the top of one of the wiki's local/config.php files, before calling authuser or any other recipes, add a line like:
session_name('XYZSESSID');
You can pick any alphanumeric name for XYZSESSID; for example, for the cs559-1 wiki you might choose
session_name('CS559SESSID');
This will keep the two wikis' sessions independent of each other.
Categories: WikiFarms
This page may have a more recent version on pmwiki.org: PmWiki:WikiFarms, and a talk page: PmWiki:WikiFarms-Talk.