Summary: An efficient way to manage a wiki farm or web server.
Version: 2.0
Maintainer: BenWilson

Link to main topic: WikiFarmAlternative

Categories: WikiFarms

Since this method of configuring a Wiki Farm does not result in a "standard" farm configuration (as documented in WikiFarms) I would recommend that this be clearly stated right at the beginning. Then mention what the advantages are to using this method and what are the disadvantages (are include("$FarmD/...") lines in recipes still a problem? If so, it should be mentioned that nearly every recipe will need to be edited on every upgrade.) so that people can make an informed choice. Right now there is a generic reference to the StepByStep method, but it's not clear to a casual reader (or non-technical administrator) that this method is anything other than an alternate set of instructions to do the same thing found in WikiFarms. If, as it appears to me, this is a configuration which was needed 10 years ago but is no longer needed then perhaps it should be marked as obsolete. Peter Bowers June 03, 2015, at 01:55 AM

Version 2.1 Discussion

I added a description of moving /pub and /cookbook out.

If you're already moving pmwiki-latest out of the web path, why do you need to move pub and cookbook away from under pmwiki-latest? Wouldn't keeping them there permit the standard use of $FarmD/cookbook and such that we are already familiar with? What additional benefit is there to moving these things to yet another directory that's outside the web path? tamouse September 20, 2011, at 05:24 AM

(More) I have to say this recipe seems to make things quite complicated. I've taken a bit of what you've done and put together a bit of a different structure. Instead of a separate directory for the shared and dynamic objects of the wiki, my structure looks like this:

 pmwiki-latest/ (root of the farm)
 ---cookbook/ (shared cookbook recipes)
 ---local/ (common configuration scripts)
 -------config.php (common configuration settings)
 -------setworkdir.php (common script that will create working paths. see below)
 -------(other common configuration settings)
 ---pub/ (common pub elements)
 ---scripts/ (shared code)
 ---var/ (per wiki dynamic area)
 ------WIKIFIELDNAME/ (directory for each field in the farm)
 ---------wiki.d/ (page store for this wiki field)
 ---------(potentially other per-wiki-field dynamic info, such as for userauth2)
 ---wikilib.d/ (page store for common pages)

The wikifields directory structure is:

 ------pub/ (symlinked to pmwiki-latest/pub/)
 ------pub/ (symlinked to pmwiki-latest/pub/)

and so on. In each wikifield, the index.php consists of:

 $FarmD = '/Users/tamara/pmwiki-latest';
 $WikiFieldName = 'wiki1';

and setworkdir.php consists of:

 <?php if (!defined('PmWiki')) exit();
 $WorkDir = "$FarmD/var/$WikiFieldName/wiki.d/";
 $LastModFile = "$WorkDir.lastmod";
 $WikiDir = new PageStore("$WorkDir\$FullName", 1);
 $WikiLibDirs = array(
 	new PageStore("$FarmD/wikilib.d/\$FullName")

and there's no need to create all sorts of $FarmX variables to make things work or rewriting of recipes.

The only disadvantage I can see to using this structure is it doesn't allow you to have each revision of pmwiki in it's own directory. I don't think there's enough of an advantage to doing that. Using the scheme above, I can pretty easily store it in a git repository and repopulate staging and production servers when the time is right.

--tamouse September 20, 2011, at 08:31 AM

Version 2.0 Discussion

This is a new explanation, so I thought it better to move discussions here.

  • I updated the implementation to include a TOC and provide a few steps to move wiki.d out of the web-accessible directory. BenWilson August 13, 2006, at 03:49 PM

Version 1.0 Discussion

Hmm, I'm not sure I understand this completely. What is the role of the pmwiki-farm directory and how do I set it up? Not that I've tried but shouldn't pmwiki-local be referenced in index.php instead? Or what have I misunderstood? jib / may 26th 2006

A typo on my part. Pmwiki-Local and PmWiki-Farm are the same directory. I have corrected the documentation. BenWilson May 26, 2006, at 02:09 PM

I think I found a other typo: "# You will need to create $FarmL," Must probably be: "$FarmL/version.php"
This is a promising set-up, but the typos make it hard to understand, like wiki-Local is still mentioned in the text. A word on how to handle installation of a new field. Like what is teh perpose of /default_install? If it's coping to the webroot of a new install there are confusing things in the text, like: /default_install doensn't contain: index.php and /local. It would be very helpful in getting the picture while reading this set-up for the first time. Beside that, Great set-up!

wiki-local is not the aforementioned typo. The typos had been fixed as of my earlier posting. The wiki-farm/local is where server-wide configuration files are placed. For example, I use the same security configuration for five different web sites. So, I have a file '/path/to/pmwiki-farm/local/security.php' that holds that configuration in common. BenWilson June 29, 2006, at 06:07 PM

I think there is also a other bug in this recipe. The use of /pmwiki-farm/pub is quiet unclear. If I use the recipe as described I end up with a set-up with a empty pub directory. Question is? Is it appropriate to update the whole content of the pub directory when you upgrade to a newer distribution. As I am not PmWiki expert at this point I don't have enough knowledge to decide on this. If I assume that this the right strategy. I have to link the pub directory to the latest directory

[Moved Correction up] BenWilson July 02, 2006, at 01:54 PM

If this is not appropriate then something else need to done to get things working properly.
like in the farm/pub link a dirs named guiedit and skins to the guiedit and skins dirs in latest/pub and make a css for custom stuff.

Anyway for now I simlink all three to get things working.


I've never had a problem with this. in the web directory, I enter ln -sf /path/to/pmwiki-farm/pub pub, and I have access to all /pub files and sub directories. Do not link to pmwiki-latest/pub! When you upgrade, you will lose any local pub-related content. This defeats the purpose of this recipe. The purpose of this recipe is to set up an easy-to-maintain installation that can be upgraded/downgraded quickly. By linking to pmwiki-latest/pub, when you upgrade, you will have to move any site-specific contents (e.g. skins) into the new pmwiki directory. BenWilson June 29, 2006, at 06:07 PM

That's correct I should be "pmwiki-farm" not "pmwiki-latest" I corrected that.

This leaves one caveat in the recipe i.e. the line: "pub -> {core_directory}/pmwiki-local/pub" and if I understand your comment correct I should be pmwiki-farm instead. If so it would be wise to correct the recipe, cause it's quite confusing on this point. If I am wrong please explain. I like to get it right. Bart

When you first start, copy pmwiki-latest/pub into pmwiki-farm (cp -R pmwiki-latest/pub pmwiki-farm/.). This gives you a start. Whenever you want to upgrade pub/skins/pmwiki, just copy that directory. BenWilson June 29, 2006, at 06:07 PM

Thanks this fills a caveat in the original recipe. Maybe a good idea to add a bit more explaining to the recipe, e.g. which directories are holding custom files and which installation files which you want to upgrade by changing symlink "latest" when a new version is available. This will make it much easier to grasp what is happening, especially for the not_jet experienced pmwiki administrator (like me ;-), how likes to set up his installation as a farm according this recipe right away after testing PmWiki. It will certainly add to the clarity of the recipe. Once in place and understood it’s really a breeze to set up just a other PmWiki driven site Bart

More typos than bugs. I have corrected the erroneous documentation to read pmwiki-farm. Originally, all the pmwiki-farm references were pmwiki-local. However, as that confused people into thinking this was related to /local, I changed it. I think I've caught them all now. Thanks BenWilson July 02, 2006, at 01:54 PM

Thanks for your response Ben. In working with this setup for some days now I see some great advantages and some minor disadvantages.

The biggest advantage: every thing goes through file linking which makes this setup suitable for a mixed farm of normal http: and SSL shttp: served sites. Which is not the case with WikiFarm Step by Step cause the pub linking via a URL.

(See 00526 and 00527 for a important issue and a workaround when using SSL shttp: )

One of the disadvantages of this set-up is the separation between the pmwiki installation and the farm directory with the separate cookbook, pub and local directory.

This results in:

  • A non standard upgrade to new pmwiki version method.
  • Usage of two additional variables $FarmL, $FarmC beside the standard $farmD
  • Non standard installation of cookbook recipes, the $FarmD in includes lines need to be changed.
  • Installation in different, non standard directory.

This can be confusing when you don’t install recipes that often or upgrade that often.

I am considering of dropping the /pmwiki-farm directory in favour of a much more transparent set-up. Where all installation file reside in one directory e.g. /pmwiki-current (In this directory basic installation and site admin added are separated in different directories by default. )

Befits are:

  • Complies with standard way for adding cookbook recipes.
  • No extra variables to take care for.
  • Standard upgrade method possible.
  • More intuitive, directories are just where you expect them.

At this moment I’ll still favour a set-up like /pmwiki-current (symlink to /pmwiki-2.1.11) cause the added flexibility. If I like to test a new installation I can copy the /pmwiki-2.1.11 directory rename it to the newest version. Upgrade this directory to newest version and change the symlink from latest back and forward between versions. But admins which don’t like this method can just ignore it and just make and use the directory /pmwiki-latest (or whatever name they like)

Try this: Keep the pmwiki-farm directory. When you upgrade, symlink directories from /pmwiki-farm to /pmwiki-pmwiki-2.3.33. This circumvents the need for $FarmC. That is, symlink /pmwiki-local/cookbook to pmwiki-pmwiki-2.3.33/cookbook. Then, when you link /pmwiki-pmwiki-2.3.33 to /pmwiki-latest@@, everything should behave as usual.
However, it has been my experience that some of the concerns you raise occur when installing new recipes. When you run the newly-installed recipes, you may have to edit the file to replace hard-links to /cookbook with $FarmC. This has become natural for me, and I have gone months between upgrades. BenWilson July 25, 2006, at 11:24 PM

Having tinkered with three fields I am also intending to moving the wiki.d directories of all fields to one directory e.g. called farm, cause I expect this will also add to a more transparent and intuitive set-up. Resulting in a "latest" directory containing all installation and configuration files and a "farm" containing the "field" content directories.

That is one way to do it, and one which I think is optimal for protecting those directories. I've not actually done that yet as I've settled in my approach.

Beside this I also wrote a readme which gives me a structured step by step instruction to quickly set up a new field, including setting all file permissions.

Next step: convert the readme into a shell script that takes the path to the new field and/or field name and builds the new field for you. I had something like this before I went to this recipe's approach. I don't add fields enough to automate. Besides, it's usually me doing a recursive copy of a certain /local, copying a index.php file and .htaccess, linking the /pub directory, and then changing the config.php. Keep the readme as a comments so you remember what's going on &ellipse; BenWilson July 25, 2006, at 11:24 PM

Please feel free to comment.

Bart July 14, 2006, at 04:26 PM


Talk page for the WikiFarmAlternative recipe (users?).