Farm Setup By Example

Summary: An alternative introduction to creating a WikiFarm

Version: 0.06

Prerequisites: PmWiki 2.x

Status: Maintained

This page explains how to install multiple wikis using a single copy of PmWiki.

Specifically, it explains how to install PmWiki (if it's a fresh installation), disable the home wiki (if you would like to), add a farm-wide configuration file, add a new wiki, and then another new wiki, then customize the wikis using bundled scripts, recipes from the Cookbook, and skins.

Introduction

There are many ways to set up a WikiFarm because PmWiki is such a flexible piece of software. In this example, we will start either from scratch or with an existing stand-alone installation, and finish with two (or two additional) freshly configured wikis, ready for authors to add content.

Here is how some terms are used in the context of this page.

wiki: A functioning Pmwiki site that has its own URL, stored wiki pages, and local configuration file (local/config.php)
WikiFarm: PmWiki configured to run multiple wikis. The term is related to the computing phrase "server farm".
home wiki: A wiki in a farm that's in PmWiki's directory. If you start with a stand-alone installation and add a wiki, the original wiki becomes a home wiki.
farm-wide: Something that affects all wikis in a farm.
local: Something that affects a certain individual wiki.
URL: A web address that you can reach with your web browser
filesystem location: A location on the server's filesystem

A home wiki may or may not be running in the directory where the PmWiki software is installed. (In this example one won't be if you're starting from scratch.) Aside from the pub/ folder, PmWiki's installation location doesn't even need to be accessible via a URL.

Install PmWiki

(If you already have a stand-alone wiki you can skip ahead to "Add a farm-wide configuration file (farmconfig.php)".)

Start by installing a fresh copy of PmWiki. In this example, we will disable the home wiki so it is not necessary to set up a wiki.d/ directory, as described in installation. The two fresh, additional wikis we will be making, will be outside the PmWiki installation directory in web-accessible directories of their own.

For this example, we will suppose that our PmWiki installation is in:

/home/someuser/public_html/pmwiki/

The URL for the home wiki then would be this:

http://www.example.com/~someuser/pmwiki/pmwiki.php

Disabling the 'home wiki'

With the fresh installation of PmWiki we get one functioning wiki, the home wiki. Soon in this example, we will be adding two (or more) additional wikis placed as you wish at any URL on your site. If you would rather use those conveniently placed wikis, and not the home wiki, this is how you can disable it.

First, we will configure home wiki not to show up if accessed. Let's create a config.php. The filesystem location of the home wiki's local/config.php file is:

http://www.example.com/~someuser/pmwiki/local/config.php

Here are it's contents, just a line to disable the home wiki:

<?php header('HTTP/1.0 403 Forbidden'); exit;

Or, if you want to return an error page, use something like this:

<?php
## config.php - Disable the home wiki for this farm.
header("HTTP/1.1 403 Forbidden");
exit('<html>
 <head><title>Forbidden</title></head>
 <body><p>Status:403 Forbidden</p></body>
</html>');

At this point, if you visit http://www.example.com/~someuser/pmwiki/ you will probably see the directory file listing. To prevent that, it would be good to create an index.php file with similar contents:

<?php
## index.php - Disable a directory listing.
header("HTTP/1.1 403 Forbidden");
exit('<html>
 <head><title>Forbidden</title></head>
 <body><p>Status:403 Directory listing forbidden.</p></body>
</html>');

and place it in this filesystem location:

http://www.example.com/~someuser/pmwiki/index.php

Now what we have is essentially a locked-down stand-alone PmWiki installation.

Add a farm-wide configuration file (farmconfig.php)

Wikis in a farm are configured farm-wide (globally, in farmconfig.php) and individually (locally, in config.php). Local configuration overrides global (see PmWiki.WikiCascades).

The farm-wide configuration file is placed in the local/ directory of the PmWiki installation:

/home/someuser/public_html/pmwiki/local/farmconfig.php

At minimum, farmconfig.php must specify $FarmPubDirUrl, the URL of the farm's pub/ directory. Here's a minimal farmconfig.php:

<?php if (!defined('PmWiki')) exit();
$FarmPubDirUrl = 'http://www.example.com/~someuser/pmwiki/pub';

Note: There's no way for PmWiki to automatically determine the URL location of the farm's pub/ directory, so it needs to be explicitly configured in 'farmconfig.php'.

Here's a slightly less minimal farmconfig.php:

<?php if (!defined('PmWiki')) exit();
## This is farmconfig.php, a global PmWiki configuration file for
## a collection ("farm") of wikis.

##  $FarmPubDirUrl is the URL for the farm-wide pub directory.
$FarmPubDirUrl = $UrlScheme.'://'.$_SERVER['HTTP_HOST'].'/~someuser/pmwiki/pub';

## Require edit authorization to view wikitext source and page history.
$HandleAuth['source'] = 'edit';
$HandleAuth['diff'] = 'edit';

Add a wiki

You can add a wiki in four simple steps.

Create a directory somewhere in the web space.
Add a wrapper script in that directory, that points to pmwiki.php in the initial installation.
Add a local configuration file
Let the PmWiki engine create a wiki.d/ directory for page storage.

For our example the directory will be wiki-one/ and the wrapper script will be an index file (index.php) in that directory:

/home/someuser/public_html/wiki-one/index.php

This script only needs one line:

<?php include('/home/someuser/public_html/pmwiki/pmwiki.php');

You could also use a relative path, rather than an absolute path:

<?php include('../pmwiki/pmwiki.php');

The URL will be either of these:

http://www.example.com/~someuser/wiki-one/
http://www.example.com/~someuser/wiki-one/index.php

The local configuration file will be in the local wiki's local/ subdirectory, so it's path will be:

/home/someuser/public_html/pmwiki/wiki-one/local/config.php

Here is an example local/config.php file:

<?php if (!defined('PmWiki')) exit();
## Title of this wiki
$WikiTitle = 'Wiki One';

## Produce a unique cookie prefix for this site.
$CookiePrefix = substr($tmp = md5(__FILE__), 0, 5).'_';

## Set an administrative password.  (String from ?action=crypt)
$DefaultPasswords['admin']='yourcryptedpassword';

## Enable graphical user interface buttons on edit pages.
$EnableGUIButtons = 1;

## Enable RSS and Atom web feeds.
if ($action == 'rss' || $action == 'atom') {
  include_once("$FarmD/scripts/feeds.php"); }

Now we have this directory structure:

wiki-one/
|-- index.php
`-- local/
    `-- config.php

After we visit this wiki's URL and prepare writable a wiki.d/ it will look like this:

wiki-one/
|-- index.php
|-- local/
|   `-- config.php
`-- wiki.d/

Add another wiki

The second new wiki will be installed in the same manner. The same wrapper script will be here this time:

/home/someuser/public_html/wiki-two/index.php

The URL will be either of these:

http://www.example.com/~someuser/wiki-two/
http://www.example.com/~someuser/wiki-two/index.php

The local configuration file goes in local/ subdirectory:

/home/someuser/public_html/pmwiki/wiki-two/local/config.php

Here are the contents of local/config.php for Wiki Two. (Only the wiki title and password are different.):

<?php if (!defined('PmWiki')) exit();
## Title of this wiki
$WikiTitle = 'Wiki Two';

## Produce a unique cookie prefix for this site.
$CookiePrefix = substr($tmp = md5(__FILE__), 0, 5).'_';

## Set an administrative password.  (String from ?action=crypt)
$DefaultPasswords['admin']='yourcryptedpassword';

## Enable graphical user interface buttons on edit pages.
$EnableGUIButtons = 1;

## Enable RSS and Atom web feeds.
if ($action == 'rss' || $action == 'atom') {
  include_once("$FarmD/scripts/feeds.php"); }

After we visit this wiki's URL and prepare a writable wiki.d/ directory to hold its wiki pages, Wiki Two's directory structure will look like this:

wiki-two/
|-- index.php
|-- local/
|   `-- config.php
`-- wiki.d/

Bundled scripts (the scripts/ directory)

If a wiki isn't a home wiki installed in the same directory as the PmWiki software you will need to make a small change to how you include a bundled script in local/config.php.

Instead of this:

include_once("scripts/somescript.php");

you will use this (with "double" quotes not 'single' quotes):

include_once("$FarmD/scripts/somescript.php");

Recipes (the cookbook/ directory)

Since each wiki in a farm is very similar to a stand-alone wiki, you can install recipes in the wiki's cookbook/ directory (you will need to create one) in the same manner as you would for a stand-alone wiki.

Better yet, you install a recipe in the farm's cookbook/ directory (the one included with the distribution) and it will become available to all of the wikis in the farm. All you need to do is make a slight change to the line that includes the recipe's script.

Instead of this:

include_once("cookbook/somerecipe.php");

you will use this (with "double" quotes not 'single' quotes):

include_once("$FarmD/cookbook/somerecipe.php");

Skins (the pub/skins/ directory)

Skins can be installed farm-wide, locally, or both. Just as with configuration variables, the local version overrides the farm-wide version if both exist.

Skins you want globally available for any wiki in the farm should be installed in the farm's pub/skins/ directory, which you need to create if it's not there. Any exclusive skin for an individual wiki belongs in that wiki's pub/skins/ directory.

Notes

A wiki outside the web document tree

Another way to establish a WikiFarm from scratch:

Unpack the PmWiki software somewhere outside the web document tree.
Move the pub/ directory to somewhere in the web space.
Add a local/farmconfig.php and set two variables:
1. Set $FarmPubDirUrl to the URL of the pub/ directory.
2. Set $SkinLibDirs to reflect the new location of your farm's moved pub/ directory.
Create wikis using the four steps.

Example farmconfig.php:

<?php if (!defined('PmWiki')) exit();
## This is farmconfig.php, a global PmWiki configuration file for
## a collection ("farm") of wikis.

##  $FarmPubDirUrl is the URL for the farm-wide pub directory
##  in the web document root on this server.
$FarmPubDirUrl = $UrlScheme.'://'.$_SERVER['HTTP_HOST'].'/pub';

## We moved pub/ - adjust $SkinLibDirs accordingly.
$SkinLibDirs = array(
  "./pub/skins/\$Skin" => "$PubDirUrl/skins/\$Skin",
  "/var/www/pub/skins/\$Skin" => "$FarmPubDirUrl/skins/\$Skin");

Whenever you move pub/ away from the default location (a subdirectory of $FarmD) you'll need to set $SkinLibDirs to reflect the new filesystem location of your farm's moved pub/ directory.

Creating empty directories

It may be less confusing to create some empty directories right from the start when a new wiki is added to the farm. A freshly-minted wiki with empty cookbook/, pub/css/, and pub/skins/ directories has a directory structure like this:

content/
|-- index.php
|-- local/
|   `-- config.php
|-- cookbook/
|-- pub/
|   |-- css/
|   `-- skins/
`-- wiki.d/

Denying direct access to directories

Your local/ and cookbook/ directories are never accessed directly by browsers in PmWiki. (That's what pub/ is for.) You can add an index.php file to prevent directory listing and a .htaccess server configuration file to deny access in those directories.

# .htaccess - Apache fileserver configuration file
# This file is in the directory to prevent the directory's
# contents from being accessed directly by browsers.
# (This closes a potential security hole.)
Order Deny,Allow
Deny from all

Contributors

Comments

See discussion at FarmSetupByExample-Talk

User notes +2: If you use, used or reviewed this recipe, you can add your name. These statistics appear in the Cookbook listings and will help newcomers browsing through the wiki.